Examples: APIs 


This article contains example programs that use APIs. It also contains examples of two exit programs. For additional information 


concerning API examples, see the System API Piogiimniag manual on the VSR1 Supplemental Manuals Web site. 


See Code disclaimer information for information pertaining to code examples. 


The examples included are: 
e Deleting Old Spooled Files 


e Changing an Active Job 


e Changing a Job Schedule Entry 


e Creating Your Own Telephone Directory 


e Creating and Manipulating a User Index 


e Creating a Batch Machine 


e Defining Queries 


e Generating and Sending an Alert 


e Diagnostic Reporting 


e Listing Directories 


e Listing Subdirectories 


e Saving to Multiple Devices 


e Scanning String Patterns 


sing COBOL Program to Call APIs 


sing the User-Defined Communications Programs for File Transfer 


sing the Control Device (QTACTLDV) API 


sing a Data Queue 


sing Environment Variables 


aving and Restoring System-Level Environment Variables 


sing ILE Common Execution Environment Data APIs 


sing the Generic Terminal APIs 


sing Profile Handles 


sing Registration Facility APIs 


sing Semaphores and Shared Memory 


sing SNA/Management Services Transport APIs 
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sing Source Debugger APIs 


e Using the Spawn Process and Wait for Child Process APIs 


Working with Stream Files 


The exit program examples are: 


e Creating a Program Temporary Fix Exit Program 


e Using the Operational Assistant Exit Program for Operational Assistant Backup 


Deleting Old Spooled Files 


The following application program runs using the Delete Old Spooled Files (DLTOLDSPLF) command. This example has three 
major parts: 


1. The DLTOLDSPLF command calls the delete old spooled files (DLTOLDSPLF) program in one of the following languages: 


Oo OPM RPG 
o OPM COBOL 
o ILEC 


2. The DLTOLDSPLF program is supplied in OPM RPG, OPM COBOL, and ILE C. It does the following: 


a. Creates a user space (QUSCRTUS API). 
b. Generates a list of spooled files (QUSLSPL API. 


c. Retrieves information from a user space using one of the following: 


m QUSRTVUS API 
m QUSPTRUS API 


d. Retrieves more spooled file attribute information received from the user space (QUSRSPLA API). 
e. Calls the CLDLT program to delete the spooled files. 

f. Sends a message to the user (QMHSNDM API). 

g. Deletes the user space (QUSDLTUS API). 


3. The CL delete (CLDLT) program does the following: 


a. Deletes the specified spooled files (DLTSPLF command). 
b. Sends a message if the spooled file was deleted (SNDPGMMSG command). 


Note: The programs and source code used as examples in the spooled file portion of this article exist only in printed form. They are 
not stored electronically on the iSeries server. 


DLTOLDSPLF Command Source 
The command source for the DLTOLDSPLF command follows: 


[OK KR KKK KK KKK KK IA A IA RA AA AA IA A A A I A I I / 


[es * / 
/* CMD: DLTOLDSPLF aif! 
/* */ 
/* LANGUAGE: CL COMMAND SOURCE * / 
/* * / 
/* DESCRIPTION: COMMAND SOURCE FOR THE DLTOLDSPLF COMMAND WHICH*/ 
/* INVOKES THE DLTOLDSPLF PROGRAM. * / 
/* * / 


[OK KK KK KKK KK KKK AA A A RR AA A IA A AA A I A I I / 


CMD PROMPT('DELETE OLD SPOOLED FILES") 
/* PARAMETERS FOR LIST OF SPOOLED FILES (QUSLSPL) */ 
PARM KWD (USRPRFNME) + 
TYPE (* SNAME) + 
LEN (10) te 
MIN (1) + 
SPCVAL (*ALL) + 
PROMPT ('User Profile Name:') 
PARM KWD (OUTQUEUE) cs 
TYPE (QUAL1) + 


MIN (1) + 
PROMPT ('Output Queue:') 
/* INFORMATION NEEDED FOR PROGRAM af 
PARM KWD (DELETEDATE) + 
YPE (*DATE) + 
PROMPT ('Last Deletion Date:") 
QUALI: QUAL TYPE(*NAME) LEN (10) SPCVAL (*ALL) 

QUAL TYPE(*NAME) LEN(10) SPCVAL(*LIBL *CURLIB ' ') 4 

PROMPT ('Library Name:') 


To create the CL command, specify the following: 


CRICMD CMD(QGPL/DLTOLDSPLF) PGM(QGPL/DLTOLDSPLF) + 
SRCFILE (QGPL/QCMDSRC) ALLOW(*IPGM *BPGM) 


To delete old spooled files, you can use one of the application programs provided in the following languages: 
e RPG 
e COBOL 
e ILEC 


RPG DLTOLDSPLF Program 


To delete old spooled files, use the following RPG program: 


He KEK KKK KK KK KKK KK KKK KKK KK KK KK KK KKK KK KK KK KK KK KK KK 
He KR KKK KKK KK KKK KKK KK KKK KK KK KK KK KK KK KK KKK KK KK KK KK 


H* * 
H* MODULE: DLTOLDSPLF * 
H* * 
H* LANGUAGE: RPG i 
H* * 
H* FUNCTION: THIS APPLICATION WILL DELETE OLD SPOOLED FILES * 
H* FROM THE SYSTEM, BASED ON THE INPUT PARAMETERS. ad 
H* * 
H* APIs USED: 7 
H* QUSCRTIUS -—- Create User Space * 
H* QUSLSPLF -—- List Spooled Files * 
H* QUSRTIVUS -—- Retrieve User Space * 
H* QUSRSPLA -—- Retrieve Spooled File Attributes * 
H* QMHSNDPM -—- Send Program Message * 
H* QUSDLTUS -—- Delete User Space us 
H* * 


He KEK KKK KK KK KK KKK KKK KKK RK KK RK KK KK KK KK KK KKK RK KK KK KK KK 
He RRR KKK KK KKK KK KK KK KKK KK KK KK KK KKK RK KKK KK KK KK KK 


E/COPY QRPGSRC, EUSRSPLA 


I "NUMBER OF SPOOLED - C MSGTXT 
I "FILES DELETED: : 

IMSGDTA DS 

I 1 35 MSGDT1 
I 36 AQQODLTCNT 
ISTRUCT DS 

I B 1 40USSIZE 
I B 5 80GENLEN 
I B 9 120RTVLEN 
I B 13 160STRPOS 
I B 17 200RCVLEN 
I B 21 240SPLF# 
I B 25 280MSGDLN 
I B 29 320MSGO# 
I 33 38 FIL# 

I 39 42 MSGKEY 
x Ea "DLTOLDSPLFQTEMP : 43. 62 USRSPC 
If '*REQUESTER u 63 82 MSGO 


ITGTDAT DS 


a 1 1 TGTCEN 
i 2 3 TGTYR 

I 4 5 TGIMTH 
I 6 7 TGTIDAY 


I/COPY QRPGSRC, QUSGEN 
I/COPY QRPGSRC, QUSLSPL 
I/COPY QRPGSRC, QUSRSPLA 

T & KK KK KK KK KK KK KK 
I* The following is copied from QSYSINC/QRPGSRC member QUSEC 

I* so that the variable length field QUSBNG can be defined 

I* as 100 bytes for exception data. The defined field is 


I* named EXCDTA. 
T KK KK I KK KK KK KK KK KK 


IQUSBN DS 

Tr Qus EC 

I B 1 40QUSBNB 

I* Bytes Provided 
I B 5 80QUSBNC 

I* Bytes Available 
I 9 15 QUSBND 

I* Exception Id 

I 16 16 QUSBNF 

he Reserved 

I* 17 17 QUSBNG 

Ex Varying length 

iL 17 116 EXCDTA 

IDATSTR DS 


1 1 DATCEN 
202 203 DATYR 
204 205 DATMTH 
206 207 DATDAY 


KKK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KK KKK KK 


KKK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKKK KKK KK KKK KK 
* 


EXECUTABLE CODE STARTS HERE x 
* 


KKK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KK KKK KK 


KKK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KK KKK KK 


* 


*ENTRY PLIST 

PARM USRNAM 10 

PARM OUTQ 20 

PARM DLTDA 7 

MOVE DLTDAT TGTDA 

Z-ADDO DLTCN 

MOVE *BLANKS QUSBN 
QUSBNB 


CREATE A USER SPACE TO STORE THE LIST OF SPOOLED FILES. 


CALL 'QUSCRTUS' 


PA USRSPC 
PA *BLANKS USEXAT 10 
PA 1024 USSIZE 
PA ™ USINIT 1 


PA 
PA 
PA 
PA 


"*CHANGE 'USAUTH 10 
*BLANKS USTEXT 50 
'*YES "USREPL 10 
QUSBN 


ZEERERER 


FILL THE USER SPACE JUST CREATED WITH SPOOLED FILES AS 
DEFINED IN THE CL COMMAND. 


+ F FF 


CALL 'QUSLSPL' 
PARM USRSPC 


I 
I 
I 
I 
c* 
c* 
c* 
c* 
c* 
c* 
c* 
c* 
Cc 
Cc 
c 
Cc 
Cc 
Cc 
Cc 
es Z-ADDO 
c* 
c* 
c* 
Cc 
Cc 
Cc 
Cc 
C 
Cc 
Cc 
€ 
Cc 
c* 
c* 
c* 
c* 
Cc 
Cc 
Cc PARM 'SPLFO1O00'FMTNM1 8 


aagaaganaagaaaagnaaaa 


PARM USRNAM 


PARM OUTO 
PARM '*ALL 'FRMTYP 10 
PARM '*ALL 'USRDTA 10 
PARM QUSBN 
* 
THE USER SPACE IS NOW FILLED WITH THE LIST OF SPOOLED FILES. * 
NOW USE THE QUSRTVUS API TO FIND THE NUMBER OF ENTRIES AND * 
THE OFFSET AND SIZE OF EACH ENTRY IN THE USER SPACE. * 
* 
Z-ADD140 GENLEN 
Z-ADD1 STRPOS 
* 
CALL 'QUSRTVUS' 
PARM USRSPC 
PARM STRPOS 
PARM GENLEN 
PARM QUSBP 
PARM QUSBN 
* 
CHECK THE GENERIC HEADER DATA STRUCTURE FOR NUMBER OF LIST * 
ENTRIES, OFFSET TO LIST ENTRIES, AND SIZE OF EACH LIST ENTRY. * 
* 
Z-ADDQUSBPQ STRPOS 
ADD 1 STRPOS 
Z-ADDQUSBPT RTVLEN 
Z-ADD209 RCVLEN 
Z-ADD1 COUNT 150 
* 
KEKE KK KKK KKK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KK KKK KKK KK KKKKKKKKAEKK 
KEKE KKK KK KKK KK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KK KKK KKKKKAEK 
* 
BEGINNING OF LOOP (DO WHILE COUNT <= QUSBPS) * 
* 
KEK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKKKKKKEK 
* 
COUNT DOWLEQUSBPS 


* 


RETRIEVE THE INTERNAL JOB IDENTIFIER AND INTERNAL SPOOLED FILE* 
IDENTIFIER FROM THE ENTRY IN THE USER SPACE. THIS INFORMATION* 
WILL BE USED TO RETRIEVE THE ATTRIBUTES OF THE SPOOLED FILE. bss 


THIS WILL BE DONE FOR EACH ENTRY IN THE USER SPACE. * 
* 
CALL 'QUSRTVUS' 
PARM USRSPC 
PARM STRPOS 
PARM RTVLEN 
PARM QUSFT 
PARM QUSBN 
NOW RETRIEVE THE SPOOLED FILE ATTRIBUTES USING THE QUSRSPLA 


API. 


+ FF 


MOVE *BLANKS JOBINF 


MOVEL'*INT' JOBINF 26 
MOVE QUSFTH QUSFXD 
MOVE QUSFTJ QUSFXF 
MOVEL'*INT' SPLFNM 10 


MOVE *BLANKS SPLF# 


CALL 'QUSRSPLA' 


PARM QUSFX 
PARM RCVLEN 
PARM 'SPLAO100'FMTINM2 8 
PARM JOBINF 
PARM QUSFXD 


PARM QUSFXF 


aaagaanagagaagaagagagaagaaaana aqgaaAaAAN 


aa 


qaaagaanaaenaaagaagaaaaa 


PARM SPLFNM 
PARM SPLF# 
PARM QUSBN 
* 
CHECK QUSFX DATA STRUCTURE FOR DATE FILE OPENED. * 
DELETE SPOOLED FILES THAT ARE OLDER THAN THE TARGET DATE * 
SPECIFIED ON THE COMMAND. A MESSAGE IS SENT FOR EACH SPOOLED * 
FILE DELETED. * 
* 
* 
MOVE QUSFX7 DATSTR 
DATCEN IFLT TGTCEN 
EXSR CLDLT 
ELSE 
DATCEN IFEQ TGTCEN 
DATYR IFLT TGTYR 
EXSR CLDLT 
ELSE 
DATYR IFEQ TGTYR 
DATMTH IFLT TGTMTH 
EXSR CLDLT 
ELSE NOT LT MTH 
DATMTH IFEQ TGTMTH 
DATDAY IFLE TGTDAY 
EXSR CLDLT 
END FOR LE DAY 
END FOR EQ MTH 
END FOR ELSE MTH 
END FOR EQ YR 
END FOR ELSE YR 
END FOR EQ CEN 
END FOR ELSE CEN 


GO BACK AND PROCESS THE REST OF 


SPACE. 
QUSBPT 
1 


ADD 
ADD 
END 


STRPOS 
COUNT 


THE ENTRIES IN THE USER 


STRPOS 
COUNT 


KKK KKK KKK KKK KKK KKK KKK KK KK KKK KKK KKK KKK KK KKK KKK KK KKK K KKK KKKKAKEK 


KKK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK 


END OF LOOP 


KKK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKKKEKEK 


KKEKKKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKKKKKK 


AFTER ALL SPOOLED FILES HAVE 


BEEN DELETED THAT MET THE 


REQUIREMENTS, SEND A FINAL MESSAGE TO THE USER. 


DELETE THE USER SPACE OBJEC 


MOVELMSGTX 


CALL 
PA 
PA 
PA 
PA 
PA 
PA 
PA 
PA 
PA 
PA 


seems 2 2.2.2 


"QMHSNDM'! 
*BLANKS 
*BLANKS 


40 
'* INFO 


1 
*BLANKS 


HAT WAS CREATED. 


MSGDT1 


MSGID 7 
MSGFIL 20 
MSGDTA 
MSGDLN 
"MSGTYP 10 
MSGQ 
MSGOQ# 
RPYMQ 10 
MSGKEY 
QUSBN 


+ 


+ FF FF F FF F F F 


C* DELETE THE USER SPACE OBJECT THAT WAS CREATED. 


ce 
GC CALL 'QUSDLTUS' 
Cc PARM USRSPC 
Cc PARM QUSBN 
ce 
ce 
CR IR IR IO I IO II ICR RO IO IR IO ORO IO ORI IO I A IK kk 
CR I I IO I IO I ICR IR IO IR IO RO IO ORI IO A I kk 
ce 
c* END OF PROGRAM 
ce 
CR I I RO I IO I ICR IR IO ICR IO OR IO OR IO A I kk 
Cc RETRN 
ce 
CGMtttteec eee eee ee cee ee ee ee ee ee ee ee eee 
ce 
Ex CLDLT SUBROUTINE 
ce 
C* THIS SUBROUTINE CALLS A CL PROGRAM THAT WILL DELETE A SPOOLED 
C* FILE AND SEND A MESSAGE THAT THE SPOOLED FILE WAS DELETED. 
* 
a Ce ee ee eee ee ee 
ce 
Cc CLDLT BEGSR 
ce 
C* KEEP A COUNTER OF HOW MANY SPOOLED FILES ARE DELETED. 
ce 
Cc ADD 1 DLTCNT 
Cc MOVE QUSFXL FIL# 
Cc CALL 'CLDLT' 
Cc PARM QUSFXK 
Cc PARM QUSFXJI 
Cc PARM QUSFXH 
Cc PARM QUSFXG 
Cc PARM FIL# 
Cc PARM QUSFXM 
Cc PARM QUSFXN 
c ENDSR 


To create the RPG program, specify the following: 


CRTRPGPGM PGM(QGPL/DLTOLDSPLF) SRCFILE (QGPL/QRPGSRC) 


COBOL DLTOLDSPLF Program 
To delete spooled files, you can use this COBOL DLTOLDSPLF program: 
KKEKKK KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KEK KKK KKK KKK KKK KKK KKKKKAEKK 


PROGRAM: DLTOLDSPLF 
LANGUAGE: COBOL 
DESCRIPTION: DELETE OLD SPOOLED FILES 


APIs USED: QUSCRTIUS, QUSLSPL, QUSRTVUS, QUSRSPLA, QUSDLTUS, 
AND QMHSNDM. 

Ce ee ee ee ee ee ee ee 

IDENTIFICATION DIVISION. 

PROGRAM-ID. DLTOLDSPLF. 

ENVIRONMENT DIVISION. 

CONFIGURATION SECTION. 

SOURCE-COMPUTER. IBM-AS400. 


+ FF + FF F HF F 


* 
* 
* 
* 
* 
* 
* 
* 
* 
* 


+ FF FF F F 


+ FF FF F F HF F 


+ 


OBJECT-COMPUTER. IBM-AS400. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
DATA DIVISION. 

FILE SECTION. 

WORKING-STORAGE SECTION. 

COPY QUSGEN OF QSYSINC-QLBLSRC. 
COPY QUSLSPL OF QSYSINC-QLBLSRC. 
COPY QUSRSPLA OF QSYSINC-QLBLSRC. 


KR KKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KK KKK KK 


* VALUES USED FOR ERROR CODE * 
KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKK KK KKK KEK KKK KKK KKK KEKKKKKKKKKKKKKKKKK 
* The following is copied from QSYSINC/QLBLSRC member QUSEC 

* so that the variable length field EXCEPTION-DATA can be defined 


* as 100 bytes for exception data. 
KKK KKK KK KKK KKK KKK KK KKK KKK KEK KKK KKK KKK KEK KKK KKK KKK KKKKKKKKKKKKKKKKKK 


01 QUS-EC. 
05 BYTES-—PROVIDED PIC S9(00009) BINARY. 
05 BYTES-AVAILABLE PIC S9(00009) BINARY. 
05 EXCEPTION-ID PIC X(00007). 
05 RESERVED PIC xX(00001) 
05 EXCEPTION-DATA PIC X(00001) 

* Varying length 
05 EXCEPTION-DATA PIC X(100). 


KR KKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKKKKEEK 


* VALUES USED FOR THE QUSCRTUS PROGRAM * 


KKK KKK KKK KK KKK KK KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKKK KKK KKKKEKEK 


01 CRTUS-INFO. 


05 CRI-SPCNAME PIC X(20) 
VALUE "DLTOLDSPLFQTEMP ae 

05 CRI-EXTATTR PIC X(10) VALUE SPACE. 

05 CRI-SPCSIZE PIC S9(9) BINARY VALUE 1024. 

05 CRI-INITSPACE PIC <VALUE TY”, 

05 CRI-AUTHORITY PIC X(10) VALUE "*CHANGE ". 

05 CRI-DESCRIPTION PIC X(50) VALUE SPACE. 

05 CRI-USRRPL PIC X(10) VALUE "*YES ee 
KKEKKKK KKK KKK KK KK KKK KKK KKK KKK KKK KEK KKK KK KKK KKK KKK KK KKKKKKKKKKKKAEK 
* VALUES USED FOR THE QUSRTVUS PROGRAM * 
KKEKKKK KK KKK KKK KEK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KK KKKKKKKK 

01 RIV-START-POS PIC S9(9) BINARY VALUE 1. 
01 RTV-LENGTH PIC S9(9) BINARY VALUE 140. 
01 RIVSPLA-JOB-ID PIC X(26) VALUE "*INT". 


KR KKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK K KKK KKKKKEK 


* VALUES USED FOR THE QUSLSPL AND QUSRSPLA PROGRAM * 


KR KKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK K KKK KKKKKEK 


01 RSPLA-DATE. 

05 R-CENTURY PIC X. 

05 R-YEAR PIC X(2). 

05 R-MONTH PIC X(2). 

05 R-DAY PIC X(2). 
01 LSPLA-FORMAT PIC X(8) VALUE "SPLFO100". 
01 LSPLA-USERDATA PIC X(10) VALUE "*ALL " 
01 LSPLA-FORMTYPE PIC X(10) VALUE "*ALL " 
01 RSPLA-JOB-NAME PIC X(26) VALUE "*INT" 
01 RSPLA-NAME PIC X(10) VALUE "*INT". 
01 RSPLA-NUMBER PIC S9(9) BINARY VALUE -1. 
01 RSPLA-FORMAT PIC X(10) VALUE "SPLA0O100 " 
01 SPLA-VAR-LENGTH PIC S9(9) BINARY VALUE 800. 
01 DLT-COUNT PIC 9(15) VALUE 0 
01 DLT-SPL-NUMBER PIC 9(6). 


KR KKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKKKKEK 


* VALUES USED FOR THE QMHSNDM PROGRAM 
KKK KK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKKKKKKKKKKKKKKK 
PIC X(7) VALUE SPACE. 
PIC X(20) VALUE SPACE. 


O01 
O1 
O1 


O1 
O01 
O1 


O1 
O1 
Ol 


KKKKKKK 


MSG-ID 
MSG-F L-NAME 
MSG-DATA. 
05 DATA-MD 


* 


PIC X(34) 


VALUE "NUMBER OF SPOOLED FILES DELETED : ". 


05 DLT-NUM-MD 
MSG-DATA-LEN 
MSG-TYPE 
MSG-QUEUE 


MSG-—Q-NUM 
RP Y-MSG 
MSG-KEY 


VALUE "*REQUESTER 


PIC X(20) VALUE SPACE. 

PIC S9(9) BINARY VALUE 54. 
PIC X(10) VALUE "*INFO ee 
PIC X(20) 


PIC S9(9) BINARY VALUE 1. 
PIC X(10) VALUE SPACE. 
PIC X(4) VALUE SPACE. 


KKEKKK KK KK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KK KKK 


* PARAMETERS THAT ARE PASSED TO THIS PROGRAM FROM THE COMMAND * 
KKEKKK KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KK KKK KKK KKK KKKKKEKK 
LINKAGE SECTION. 
01 PARM-USERNAME 
01 PARM-OUTQ 
01 PARM-DATE. 


05 P-CENTURY 
05 P-YEAR 
05 P-MONTH 
05 P-DAY 


PIC X(10) 
PIC X(20) 


PIC X. 


PIC X(2). 


PIC X(2 


PIC X(2). 


KKK KKK KKK KK KKK KK KKK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KKK KKKKKEEK 


* BEGINNING OF EXECUTABLE CODE. 
KKEKKK KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KK KK KKKKKKKKKKKKKEK 
PROCEDURE DIVISION USING PARM-USERNAME, 

PARM-OUTQ, 
PARM-DATE. 


MAIN-PROGRAM. 


+ 


* 


KKK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KKK KKK KK KK KKK 


* INITIALIZE ERROR CODE STRUCTURE. 


* 


KKK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KKK KKK KK KK KKK 


MOVE 116 TO BYTES-PROVIDED. 


MOVE 0 TO BYTES-AVAILAB 


MOVE SPACES TO 


LE 


EXCEPTION-ID. 


MOVE SPACES TO 


RESERVED 


MOVE SPACES TO 


OF QUS-EC. 
EXCEPTION-DATA. 


KEK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KKK KKK KK KK KKK 


* CREATE THE USER SPACE 


USING INPUT PARMS FOR THE CALL * 


KKK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK 


CALL "QUSCRTUS" 


USING CRT-SPCNAME, 
CRT-EXTATTR, 
CRT-SPCSIZE, 
CRT-INITSPACE, 
CRT-AUTHORITY, 
CRT-DESCRIPTION, 
CRT-USRRPL, 
QUS-EC. 


KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KKK KKKKK KK KKK 


* LIST THE SPOOLED FILES TO THE USER SPACE OBJECT. * 


KKK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK 


CALL "QUSLSPL" 


USING CRI-SPCNAME, 
LSPLA-FORMAT, 
PARM-USERNAME, 


+ F FF 


+ FF HF 


+ FF HF 


PARM-OUTQ, 
LSPLA-FORMTYPE, 
LSPLA-USERDATA, 
QUS-EC. 


KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK 


* RETRIEVE ENTRY INFORMATION FROM THE USER SPACE. * 
Pe ee ee ee ee ee ee oe ee ee ee ee oe ee ee ee ee ee ee eee cee 


CALL "QUSRTVUS" USING CRT-SPCNAME, 
RIV-START-POS, 
RTV-LENGTH, 
QUS-GENERIC-HEADER-0100, 
QUS-EC. 


KKK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK 


* IF ANY SPOOLED FILES WERE FOUND MATCHING THE SEARCH © 
* CRITERIA, RETRIEVE DETAILED INFORMATION AND DECIDE fm 
* WHETHER TO DELETE THE FILE OR NOT. * 


KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK 


IF NUMBER-LIST-ENTRIES OF QUS-GENERIC-HEADER-0100 
GREATER THAN ZERO THEN 
ADD 1 TO OFFSET-LIST-DATA OF QUS-GENERIC-HEADER-0100 
GIVING RTV-START-POS. 
PERFORM CHECK-AND-DELETE THROUGH 
CHECK-AND-DELETE-END NUMBER-LIST-ENTRIES 
OF QUS-GENERIC-HEADER-0100 TIMES. 


KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KKK KKK KK KK KKK 


* CALL THE QUSDLTUS API TO DELETE THE USER SPACE * 
* WE CREATED, AND TO SEND A MESSAGE TELLING HOW MANY * 
* SPOOLED FILES WERE DELETED. * 


KKK KKK KK KK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KKK KKK KK KK KKK 


CALL "QUSDLTUS" USING CRT-SPCNAME, 
QUS-EC. 


MOVE DLT-COUNT TO DLT-NUM-MD. 
CALL "QMHSNDM" USING MSG-ID, 
MSG-FL-NAME, 
MSG-DATA, 
MSG-DATA-LEN, 
MSG-TYPE, 
MSG-QUEUE, 
MSG-Q-NUM, 
RPY-MSG, 
MSG-KEY, 
QUS-EC. 


STOP RUN. 


KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KKK KKK KK KK KKK 


* CHECK THE DATE OF THE SPOOLED FILE. IF IT IS OLDER * 
* OR EQUAL TO THE DATE PASSED IN, CALL THE PROCEDURE * 
* TO DELETE THE SPOOLED FILE. * 


KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKKKKKKK KK KKK 


CHECK-AND-DELETE 


CALL "QUSRTVUS" USING CRT-SPCNAME, 
RIV-START-POS, 
SIZE-EACH-ENTRY OF 
QUS-GENERIC-HEADER-0100, 
QUS-SPLF0100, 
QUS-EC. 


KKK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KK KKKK KK KKK 


+ 


+ F FF 


+ F 


+ FF F F 


* ADVANCE TO NEXT SPOOLED FILE FOR PROCESSING THE CHECK * 


* AND DELETE. * 
eee cee cece ee ee ee ee ee ee ee ee aero 


ADD SIZE-EACH-ENTRY OF QUS-GENERIC-HEADER-0100 TO 
RTV-START-POS GIVING RTV-START-POS. 


KKK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK 


* RETRIEVE THE ATTRIBUTES FOR THE SPOOLED FILE TO GE * 
* THE CREATE DATE FOR THE SPOOLED FILE. x 


KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK 


CALL "QUSRSPLA" USING QUS-SPLA0100, 
SPLA-VAR-LENGTH, 
RSPLA-FORMAT, 
RSPLA-JOB-NAME, 
INT-JOB-ID OF QUS-SPLF0100, 
INI-SPLF-ID OF QUS-SPLFO0100, 
RSPLA-NAME, 
RSPLA-NUMBER, 
QUS-EC. 


MOVE DATE-FILE-OPEN OF QUS-SPLA0100 TO RSPLA-DATE. 


KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK 


* COMPARE THE CREATE DATE WITH THE DATE THAT WAS PASSED * 


* IN AS PARAMETER. * 
Tee cc eee ee ee ee ee ee ee ee ee ore ce ae ce 


IF R-CENTURY IS LESS THAN P-CENTURY THEN 
PERFORM DLT-SPLF THROUGH DLT-SPLF-END 
ELSE 

IF R-CENTURY IS EQUAL TO P-CENTURY THEN 


IF R-YEAR IS LESS THAN P-YEAR THEN 
PERFORM DLT-SPLF THROUGH DLT-SPLF-END 
ELSE 
IF R-YEAR IS EQUAL TO P-YEAR THEN 
IF R-MONTH IS LESS THAN P-MONTH THEN 
PERFORM DLTI-SPLF THROUGH DLT-SPLF-END 
ELSE 
IF R-MONTH IS EQUAL TO P-MONTH THEN 
IF R-DAY IS LESS THAN OR EQUAL TO P-DAY THEN 
PERFORM DLT-SPLF THROUGH DLT-SPLF-END. 


CHECK-AND-DELETE-END. 


ee ee ee ee 
* THIS IS THE PROCEDURE TO DELETE THE SPOOLED FILE. cs 
* ALL OF THE SPOOLED FILES WITH CREATE DATE OLDER OR * 
* EQUAL TO THE DATE PASSED IN AS PARAMETER WILL BE * 
* DELETED. © 
ee ee ee ee ee ee 


DLT-SPLF 


ADD 1 TO DLT-COUNT. 
MOVE SPLF-NUMBER OF QUS-SPLA0100 TO DLT-SPL-NUMBER. 


CALL "CLDLT" USING SPLF-NAME OF QUS-SPLAO100, 
JOB-NUMBER OF QUS-SPLAO100, 
USR-NAME OF QUS-SPLA0100, 
JOB-NAME OF QUS-SPLAO100, 
DLT-SPL-NUMBER, 
FORM-TYPE OF QUS-SPLAO100, 
USR-DATA OF QUS-SPLAO0100. 


DLT-SPLF-END. 


To create the COBOL program, specify the following: 


CRICBLPGM PGM(QGPL/DLTOLDSPLF) 


ILE C DLTOLDSPLF Program 


To delete spooled files, you can use this ILE C DLTOLDSPLF program: 


SRCFILE (QGPL/QCBLSRC) 


[KK RK KK KKK KK A IA IA A RR A IAA AA A A I A I I 


PROGRAM: 


LANGUAGE: 


DLTOLDSPLF 


ILE C for OS/400 


DESCRIPTION: THIS IS AN EXAMPLE PROGRAM FOR THE USE OF 


APIs USED: 


HE FLOW OF 


USER SPACES WRITTEN IN ILE C for OS/400. 
THIS PROGRAM IS AS FOLLOWS: 
CREATE A USER SPACE USING QUSCRTUS 


GET LIST OF SPOOLED FTI 
USING QUSLSPL 
(3) KEEP POINTER TO ENTRY 
(4) ENTER LOOP 
RETRIEVE LIST ENTRY 
RE 
IF SPOOLED FILE IS TOO OLD 
DELETE SPOOLED FILE 
INCREMENT DELETE COUNTER 
END LOOP 
(5) DELETE USER SPACE 
QUSCRIUS, QUSLSPL, QUSRSPLA, QUSPTRUS, 


QMHSNDPM, AND QMHSNDM. 


QUSDLTUS, 


LES IN THE USER SPACE 


iIST IN THE USER SPACE 


RIEVE MORE INFORMATION USING QUSRSPLA 


[KK RK KK KKK KK IK A AA A A RR A A IA A A I A I A I I 


ude 
ude 
ude 
ude 
ude 
ude 
ude 
ude 
ude 
ude 
ude 


#incl 
#incl 
#incl 
#incl 
#incl 
#incl 
#incl 
#incl 
#incl 
#incl 
#incl 


<string.h> 
<stdio.h> 
<qusec.h> 
<qusgen.h> 
<quscrtus.h> 
<quslspl.h> 
<qusptrus.h> 
<qusrspla.h> 
<qusdltus.h> 
<qmhsndm.h> 
<qmhsndpm.h> 


/*strcpy, 


strncpy, 


strcmp 


/*Error code structures 


/*General 
/*Linkage 
/*Linkage 
/*Linkage 
/*Linkage 
/*Linkage 
/*Linkage 
/*Linkage 


#pragma linkage (CLDLT, OS) 


void CLDLT (char 
char 
char 
char 
char 
char 


char 
void error_check 


Qus_Generic_Header 
char *list_section; 


file _name[10 
job_number [6 
usr_name[10] 
job_name[10] 
file_number[ 
form_type[10 
usr_data[10] 


l, 
l, 


zx 


, 


, 


él, 
] 
) 


(void) ; 


_0100_t *space; 


Qus_SPLFO100_t *entry_list; 
Qus_SPLA0100_t *Rcv_Spl_Var; 


[BORK RK KK KK KKK KK IA AA AA A I A AAA A A A A / 


/* PARMS FOR CLDLT 


user space structures 


info, 
info, 
info, 
info, 
info, 
info, 
info, 


structures 
structures 
structures 
structures 
structures 
structures 
structures 


for 
for 
for 
for 
for 
for 
for 


QUSCRTIUS 


QUSLSPI 


Ly 


QUSPTRUS 


QUSRSPI 


LA 


QUSDLTUS 


QMHSNDM 


QMHSNDPM 


*/ 


*/ 


[ROKK RK KKK KK KK KI IA AA IA A A AAA A A a A oe I / 


char job_nmbr[6]; 
char usr_nm[10]; 
char job_nm[10]; 
char sp_job_name[10]; 
char sp_spl_number [6]; 


char File _Number[] = "*LAST "; 
[KK RK KK KKK KK KK A A IA A I A A AAA A A I A A / 
/* PARMS FOR QUSLSPL */ 


[KK RK KKK KK KKK KK IA AA A IA I A A AA A A I A A / 


char frmt[8]; 

char usr[10]; 

char OutQ_Nm[20]; 
char 1ls_frm_typ[10]; 
char Usr_dat[10]; 


[KK RK KKK KK KK KK AR AA AA A I AA A AAA A A a A a / 


/* PARMS FOR QUSRSPLA */ 
[KK RK KK KK KK KK IA AA AA IA I A AA AAA A A a A a / 
char Rev_Var[724]; 

int Rev_lgth = 724; 

char Rtv_Fmt [8]; 


char Qal_Jb_Nam[] = "*INT Me 

char Splf_Name[] = "*INT Ms 

int Splf_Number = -1; 

[OK KK KK KKK KK KK IA AA AA A I I I AA A AA A A A a / 
/* PARMS FOR QUSCRTUS */ 


[KK KK KKK KKK IK IA IA AA IA I I I AA AAA AA A A I A / 


char spc_name[20]; 

char ext_atr[10]; 

int initial_size; 

char initial_value[1]; 

char auth[10]; 

char desc[50]; 

char replace[10]; 

[OK KK RK KK KKK IK IA AA IA IA I I AA AA A A A A I A / 


/* PARMS FOR QMHSNDPM AND QMHSNDM */ 
[KK RK KK KK KK IK IA AA IA A I AA A AAA A A A a / 
char msg_id[7]; 

char msg_fl_name[20]; 

char msg_data[50]; 

int msg_data_len; 

char msg_type[10]; 

char pgm_queue[10]; 

int pgm_stk_cnt; 

char msg_key[4]; 


[KKK KR KK KK KKK IK IA AA IA I AA AAA A A A A / 


/* PARMS FOR QMHSNDM +) 
[KK RK KK KK KK KKK IA IA AA A I I AA AA AAA A A a A a / 
int msg_q_num; 

char msg_queue[20]; 

char rpy_mq[10]; 


[KK RK KK KK KK KI IA AA AA A I A A A AA IA A A a / 


/* MISCELLANEOUS VARIABLES */ 
[KKK KK KK KKK KK IA AA A IA I A A AA A A I A I A / 
char pack_dlt_count [15]; 

int dlt_cnt; 

int count; 

char tmp_spl_number[7]; 

char dlt_date[7]; 

char spc_date[7]; 

int api_code; 

Qus_EC_t err_code; 


[KKK KK KKK KK KKK IA IA IA IA I AA A AA AA I AA a A A / 


/* PROCEDURE TO CHECK THE ERRCODE RETURNED FROM CALLS TO APIs */ 


[KKK KK KK KK KKK IA AA A IA I AA A AA A A A I a / 


void error_check (void) 


{ 


if (err_code.Bytes_Available != 0) { 


strncpy (msg_id, "CPF9898",7); 

strncpy (msg_fl_name, "QCPFMSG *LIBL ",20); 
strncpy (msg_data,"An error has occurred calling ",29); 
switch (api_code) { 


case 1 : strncat (msg_data, "QUSCRTUS.",9); 
case 2 : strncat (msg_data,"QUSLSPL. ",9) 
case 3 ( ",9); 
case 4 : strncat (msg_data, "QUSRSPLA.",9); 
case 5 : strncat (msg_data, "QUSDLTUS.", 9) 
6 . ( weg) 
t ( ",9) 


, 


strncat (msg_data, "QUSPTRUS. 


, 


, 


case strncat (msg_data, "OQMHSNDM. 
defaul strncat (msg_data, "UNKNOWN. 
} 
msg_data_len = 38; 
strncpy (msg_type, "*ESCAPE WL OD): 7 
strncpy (pgm_queue, "* ",10); 
pgom_stk_cnt = 1; 


QMHSNDPM (msg_id,msg_fl_name,msg_data,msg_data_len,msg_type, 
pgm_queue,pgm_stk_cnt,msg_key, &err_code) ; 
} 
} 


[KOK KK KK KKK KK KKK IR IA IA IA I I AA AA AA A IA A a I A / 


/* START OF MAINLINE aA 


[ORK RK KK KK KKK KK IR AA AA IA I A AAA AA A A I I A / 


main(argc, argv) 
int argc; 
char *argv[]; 


{ 


[ORK RK KKK KK KK KK IK IA IA IA I I A AA AA A A I He I / 


/* Read in and assign the command-line arguments to respective */ 
/* variables S/- 
[OK KK KK KK KKK KK IA AA IA A I I A AAA AA AA A A a I A / 
strncpy(usr,argv[1],10); 

strncpy (OutQ_Nm,argv[2],20); 

strncpy (dlt_date,argv[3],7); 


[ORK RK KK KKK KKK KKK IK IA A A I I A A AAA AA A A I I I / 


/* Assign value to specific variables in the program af, 
[OK KK KK KKK KK KK IK IA IA IA I I A AAA AIA IA A a I I / 
strcpy (spc_name, "DLTOLDSPLFQTEMP be 

memset (ext_atr,' ',10); 

initial_size = 1024; 

strcepy (initial_value," "); 

strcpy (auth, "*CHANGE eye 

memset (desc,' ',50); 

strcpy (frmt, "SPLF0100") ; 

strcpy (replace, "*YES a 

strcpy (ls_frm_typ, "*ALL ™).5 

strcpy (Usr_dat, "*ALL Mp3 

strcpy (Rtv_Fmt, "SPLA0100"); 


[ORK RK KKK KK KK KK AR IA IA A I I A AAA AA A A I I A / 


/* Call external program to create a user space */ 

[KK RK KKK KK KKK KK IA AA AA A I A AA AA A A A I I A / 

err_code.Bytes_Provided = 0; 

api_code = 1; 

QUSCRTUS (spc_name, ext_atr,initial_size, initial_value, auth, desc, replace, 
&err_ code); 

[KK RK KKK KK KK KKK IR IA IA A I I A AAA AA A A a I A / 


/* Call external program to list spooled files into user space */ 
KKK KK KK KKK KKK KKK KKK KKK KKK KEK KKK KKK KKK KKK KKK K KKK KKK KKKKKKKKKKKKKKKKKKK 
/ / 


api_code = 2; 
QUSLSPL(spc_name, frmt, usr, OutQ_Nm, 1ls_frm_typ, Usr_dat, &err_code) ; 


[KK RK KK KKK KKK IK AA IA A I AA AA AAA AA IA A a Ie A / 


/* Call external program to get a pointer to the user space */ 
/* and get addressability to the list data section. if. 
[OK KK KK KK KK KR IK IA IA IA I I A AAA IA A A a I I / 
api_code = 3; 

QUSPTRUS (spc_name, &Space, &err_code) ; 

list_section = (char *) space; 

list_section = list_section + space->Offset_List_Data; 


entry_list = (Qus_SPLF0100_t *) list_section; 
dlt_cnt = 0; 
count = 1; 


[KK RK KK KKK KK KK IR IA IA IA I A AAA A AA IA A a I A / 


/* Loop through the entry list and delete old spooled files */ 


[KK RK KK KK KK KR IR AA IA A I I A AAA AAA AA A A I I 


while (count <= space->Number_List_Entries) { 
[ORK RK KK KKK KK KK IR IA AA A I A AAA AA AA AA A A a I A / 


/* Call external program to retrieve more spool information */ 
[RK RK KK KKK KK KK IR IA AA A I A AA AAA AA A A a He a / 
api_code = 4; 
QUSRSPLA (Rcv_Var, Rcev_lgth, Rtv_Fmt, Qal_Jb_Nam, 
entry_list-—>Int_Job_ID, entry_list-—>Int_Splf_ID, 
Splf_Name, Splf_Number, &err_code) ; 
Rev_Spl_Var = (Qus_SPLA0100_t *)Rcv_Var; 
strncpy (spc_date, Rcv_Spl_Var->Date_File_Open,7) ; 
[OK KK KK KK KK KR IR AA AA IA I A AAA A A A A I I 


/* If spooled file is too old delete it *f 
[KK RK KKK RK KK KKK IR IA AA IA I I I A A AIA AA IA IA I a I A / 
if (strncmp(spc_date,dlt_date,7) <= 0) { 
strncpy (job_nm, Rcv_Spl_Var->Job_Name, 10); 
strncpy (job_nmbr, Rcv_Spl_Var->Job_Number, 6) ; 
strncpy (usr_nm, Rcv_Spl_Var->Usr_Name, 10); 
strncpy (sp_job_name, Rcv_Spl_Var->Splf_Name,10) ; 


[OK KK KK KKK KK KKK IR IA IA IA I A AAA AA A A A I a I 


/* Convert the spooled file number to character. if 
[OK KK KK KKK KK KK KK AA IA A I I A AAA AA AA A a I / 
memcpy (sp_spl_number," BO) 7 
sprintf (tmp_spl_number, "%d",Rcv_Spl_Var->Splf_Number) ; 
memcpy (sp_spl_number,tmp_spl_number, strlen (tmp_spl_number) ); 


[ORK RK KK KKK KK KK IA IA IA IA I A AAA AA A A a I A / 


/* Delete the spooled file. Be 
[ORK RK KK KKK KK KKK IA AA IA A I A AAA AA A A a / 
CLDLT (sp_job_name, job_nmbr,usr_nm, 
job_nm, sp_spl_number,1ls_frm_typ,Usr_dat); 
dlt_centt++; 
}e PELE AS 
strcpy(spc_date," "); 
count++; 
entry_list++; 
} /*WHILE*/ 


[OK KK KK KKK KK KK IR IA IA IA I I A AA AA AA A A I a I / 


/* Remove the user space */ 
[KK RK KK KKK KKK KR IR IA IA IA I A AA AA A A A I a I a / 


api_code = 5; 
QUSDLTUS (spc_name, &err_code); 


[KK RK KK KK KK KKK IR IA AA IA I I A AAA AA AA A A I I I 


/* Send final message to user indicating number of spooled files af 
/* deleted. wad 
[OK KK KK KK KK KKK IA IA AA IA I A AAA AA A A A I a oe A / 
api_code = 6; 

strncpy (msg_id," a i 

strncpy (msg_fl_name," WZOs) 2 

sprintf (msg_data,"Number of spooled files deleted: %d", dlt_cnt); 
msg_data_len = strlen(msg_data) ; 

strncpy (msg_type, "*INFO HF 10) 3 


strncpy (msg_queue, "*REQUESTER AAO) lor 


msg_q_num = 1; 

strncpy (rpy_mq," ",10); 

QMHSNDM (msg_id,msg_fl_name,msg_data,msg_data_len,msg_type, 
msg_queue,msg_q_num,rpy_mq,msg_key, &err_code); 

} 

To create an ILE C program, specify the following: 


CRIBNDC PGM(QGPL/DLTOLDSPLF) SRCFILE (QGPL/QCSRC) 


CL Delete (CLDLT) Program 


The DLTOLDSPLF program, written in OPM RPG, OPM COBOL, or ILE C, calls a CL program named CLDLT. The CLDLT 
program deletes the spooled files and the user space. The following is the CL source for the CLDLT program. 


[KK RK KKK KKK KKK I IA A A A A A A IA IA A A A AI A I I / 


ag * / 
/* PROGRAM: CLDLT */ 
/* x 
/* LANGUAGE: CL */ 
/* * / 
/* DESCRIPTION: THIS PROGRAM WILL DELETE A SPECIFIC SPOOLED FILE as 
/* USING THE DLTSPLF COMMAND AND SEND A MESSAGE WHEN */ 
/* HE FILE IS DELETED. */f 
fag * / 
fs bard 
[ORK RK KK KK KK KK KI A A A A A A A IA A A A A A A I I / 
/* * / 
PGM (&FILNAM &JOBNUM &USRNAM &JOBNAM &FILNUM &FRMTYP &USRDTA) 

fs a 
/* KKK KK KKK KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KEK KKK KKK KKK KKK KK KKK KKK KKKK x/ 
/* * / 
/* DECLARE SECTION rand 
/* xf 
[ORK RK KK KKK KK KK A A A A A A A IA AA A A A A I A I I / 
how *«/ 


DCL &FILNAM *CHAR 10 
DCL &JOBNUM *CHAR 6 

DCL &USRNAM *CHAR 10 
DCL &JOBNAM *CHAR 10 
DCL &FILNUM *CHAR 6 

DCL &FRMTYP *CHAR 10 
DCL &USRDTA *CHAR 10 
MONMSG CPF0000 


ps * / 
[BORK RK KK KKK KKK IK AA A A A A A A A A A A A A I I / 
is * / 
/* EXECUTABLE CODE ia A 
/* Ay 
[BKK RK KKK KK KK KK IA A A A A A RR IA A A A A A A I I / 
/* * / 
DLTSPLFE FILE (&FILNAM) + 


JOB (& JOBNUM/ &USRNAM/ & JOBNAM) + 

SPLNBR (&FILNUM) 7 

SELECT (&USRNAM *ALL &FRMTYP &USRDTA) 

SNDPGMMSG MSG('Spooled file ' *CAT &FILNAM *CAT + 
" number ' *CAT &FILNUM *CAT ' job ' + 


*CAT &JOBNUM *CAT uy! + 
*CAT &USRNAM *CAT '/' *CAT &JOBNAM *CAT + 
" deleted.') + 


TOUSR (*REQUESTER) 
ENDPGM 


To create the CL program, specify the following: 


CRICLPGM PGM(QGPL/CLDLT) SRCFILE(QGPL/QCLSRC) 


Changing an Active Job 


This command interface to the Change Active Jobs (CHGACTJOB) program can reduce the run priority of active jobs with the same 
name. You can also reduce the run priority of jobs using a specified user name. You may: 


e Specify a job name or the *ALL value. 


e Specify the user name as the *ALL value. 


e Use the default run priority of 99. 


The CHGACTJOB command ensures that one of the following is true: 


e Not all jobs were specified. 
e@ The *ALL value was not specified for the JOB parameter. 


e@ The *ALL value was not specified for the USER parameter. 


This example uses the following APIs: 
e Create User Space (QUSCRTUS) 


e@ List Job (QUSLJOB) 
e Retrieve User Space (QUSRTVUS) 


e Retrieve Job Information (QUSRJOBI 


The following is the message description needed for the Change Active Jobs (CHGACTJOB) command: 


ADDMSGD MSGID(USR3C01) MSGF(QCPFMSG) + 
MSG ('JOB(*ALL) is not valid with USER(*ALL)') SEV(30) 


The following is the command definition for the CHGACTJOB command: 


CMD PROMPT ('Change Active Jobs') 
/* CPP CHGACTJOB */ 
PARM KWD (JOB) TYPE(*NAME) LEN(10) + 


SPCVAL((*ALL)) MIN(1) + 
PROMPT ('Job name: ') 


PARM KWD (USER) TYPE(*NAME) LEN(10) DFT(*ALL) + 
SPCVAL((*ALL) (*CURRENT)) PROMPT('User + 
name:') 

PARM KWD (RUNPTY) TYPE(*DEC) LEN(5 0) DFT(99) + 
RANGE (00 99) PROMPT('Run priority:') 

DEP CTL(&USER *EQ *ALL) PARM((&JOB *NE *ALL)) + 


NBRTRUE (*EQ 1) MSGID(USR3C01) 


To create the command, specify the following: 


CRTCMD CMD (QGPL/CHGACTJOB) PGM(QGPL/CHGACTJOB) + 
SRCF ILE (QGPL/CMDSRC) 


The following is the command-processing program that is written in CL to list the active jobs and reduce the run priority if necessary: 


/* KR KK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK x/ 


/* PROGRAM: CHGACTJOB */ 


/* 
/* 
/* 


LANGUAGE: CL 


DESCRIPTION: THIS PROGRAM WILL REDUCE THE RUN PRIORITY OF ACTIVE 


JOBS WITH THE SAME NAME. 


APIs USED: QUSCRTUS, 


KK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KKK KK KKK KK KKK 


PGM 


Input parameters 


DCL 


DCL 


DCL 


Local variables 


DCL 


DCL 


DCL 


DCL 


DCL 


DCL 


DCL 


DCL 


DCL 


DCL 


DCL 


DCL 


DCL 


DCL 


DCL 


DCL 


QUSLJOB, QUSRTVUS, QUS 


PARM(&JOB &USER &RUNPTY) 


VAR (&JOB) 


VAR (&USER) 


VA 


TYPE(*CHAR) LE 


/* Input job name */ 


TYPE (*CHAR) L 


/* Input user name */ 
VAR (&RUNPTY) 
/* Input run priority */ 


/* 


R (& 


R (&DEC8) 
User space offset 
R (& ELEN) 
List job entry length in decimal 8,0 + 


RJOBI 


N(10) + 


EN(10) + 


USER) 


TYPE (*DEC) 


RJOB) TYPE(*CHAR) L 
Retrieve job name */ 


TYPE (*CHAR) 


nput run 


LEN (5 0) + 


EN(10) + 


LEN (10) 


etrieve user name */ 
NBR) TYPE(*CHAR) L 


EN(6) + 


etrieve job number */ 
UNPTYC) YPE (*CHAR 


+ 


) LEN(5) + 


UNPTY8 
et 


ieve 


) TYPE (*DEC) 


4 */ 


UNPTY5 


e7 
TY5 


or 
UN 


R 
R 
R 
R 
R 
I 
R 
R 
binary 
R 
R 
f 
R 
R 
RUNPTY4 
R 


Current 


R (& USRSPC) 
UE ('CHGA QTEMP 
User space name for APIs */ 
R(&EUSRSPC) TYPE(*CHAR 
User space name for commands */ 


R (& JOBNAME ) LEN(26) + 


UE (' 


Number 


r 
a 
P 
etrieve 
m 
P 


) TYPE (*DEC) 


C) TYPE(*CHA 
) TYPE (*CHAR 
TYPE (*CHAR) 


job number 
TYPE (*CHAR) 


) TYPE (*CHAR 


YPE(*CHAR) L 


R) LEN(5) + 
etrieve run priority in character form */ 


LEN(5 0) + 
run priority in decimal 5,0 + 


) LEN(4) + 


LEN (6) 
*/ 


) 


) LEN(10) + 


LEN (20) + 


*ALL ') + 


Full job name for list job 
R(&BIN4) T 


EN (4) + 


Sif: 


of jobs for list job and + 


LOOP ) 
Number 


YPE(*DEC) LEN(8 0) 4 


of jobs from 


YPE(*DEC) LEN(8 0) 4 


form */ 


R (& ELENB) 


form */ 


YPE(*DEC) LEN(8 0) 4 


TYPE (*CHAR) 


LEN (4) 4 


User space offset in binary 4 form 


list job */ 


List job entry length in binary 4 + 


priority in character form */ 
LEN(8 0) + 
run priority after convert from + 


etrieve run priority in binary 4 form */ 
R (& NUMBER) 


*/ 


in decimal 8,0 form */ 


aA 
ae 
ef 


/* 
/* 


/* 
/* 
/* 


/* 
/* 


/* 
/* 
/* 


DCL VAR(&LJOBE) TYPE(*CHAR) LEN(52) + 


/* Retrieve area for list job entry */ 


DCL VAR(&INTJOB) TYPE(*CHAR) LEN(16) + 


/* Retrieve area for internal job id */ 


DCL VAR(&JOBI) TYPE(*CHAR) LEN(104) + 


/* Retrieve area for job information */ 


DCL VAR(&JOBTYPE) TYPE(*CHAR) LEN(1) + 
/* Job type */ 


Start of executable code 


Retrieve job number to use for local user space name 


RIVJOBA NBR (&NUMBER) 
CHGVAR VAR(%SST(&USRSPC 5 6)) 
CHGVAR VAR (&EUSRSPC) 


Delete user space if it already exists 


DLTUSRSPC USRSPC(QTEMP/&EUSRSPC) 


MONMSG CPFO000 


Create user space 


VALUE (&NUMBER) 
VALUE (%SST(&USRSPC 1 10) ) 


CALL QUSCRTUS (&USRSPC 'CHGACTJOB ' X'00000100"' ' 
"*ALL r+ 
'CHGACTJOB TEMPORARY USER SPACE- 


") 


Set up job name for list jobs 


CHGVAR VAR (%SS1 


[(&JOBNAME 1 10)) VALUE (&JOB) 


CHGVAR VAR(%SS1 


[(&JOBNAME 11 10)) VALUE (&USER) 


List active jobs with job name specified 


CALL QUSLJOB (&USRSPC 'JOBLO100' 


'*ACTIVE t) 


Retrieve number of entries returned. Convert to decimal and 
if zero go to NOJOBS label to send out 


CALL QUSRTVUS (&USRSPC X'00000085' 


&BIN4) 


CHGVAR & LOOP 


IF COND ( & LOOP 


Retrieve list entry length, 
Retrieve list entry offset, 
to set the position. 


SBINARY (&BIN4) 


convert to decimal. 
convert to decimal, 


"No jobs' 


& JOBNAME + 


message. 


X'00000004" + 


I 
0) THEN (GOTO CMDLBL (NOJOBS) ) 


and add one 


if 
ba 


*/ 
xf 
my 


aif 
xf 


mf 
ey A 
*/ 


AL 


/* 
/* 
/* 


/* 
/* 
/* 
/* 
/* 


LOOP: 


spool writer, 


CALL QUSRIT 


CHGVAR 


CALL QUSRIT 


CHGVAR 
CHGVAR 


IF 


CHGVAR 


CALL QUSRTVUS 


CHGVAR 


CALL QUSRJOBI 


CHGVAR 
IF 


Copy run priority, 


CHGVAR 
CHGVAR 
CHGVAR 
IF 


Retrieve job name, 


CHGVAR 
CHGVAR 
CHGVAR 
CHGVAR 
CHGVAR 


['VUS 
& ELENB ) 
&ELEN 


(&LOOP 


['VUS 

&BIN4) 
&DEC8 

VAR (&DEC8) 


= 0) 


SBINARY (&BIN4) 
(&USRSPC &BIN4 &ELENB + 


& LJOBE) 


VAR (& INTJOB) 
(&JOBI X'00000068' 


TALENT 


(&USRSPC X'00000089' 


(&USRSPC X'0000007D' 


X'00000004" + 


SBINARY (&ELENB) 
X'00000004' + 


SBINARY (&BIN4) 
VALUE (&DEC8 + 1) 


Loop for the number of jobs until no more jobs then go to 
LDONE label 


THEN (GOTO ALLDONE) 


Convert decimal position to binary 4 and retrieve list job entry 


&DEC8 


Copy internal job identifier and retrieve job information for 
basic performance information. 


VALUE (SST (&LJOBE 27 16) ) 
"JOBIO100'" + 


& INTJOB) 


Copy job type and if subsystem monitor, 
or SCPF system job then loop to next job 


VAR(&JOBTYPE) VALUE(%SST(&JOBI 61 1)) 

COND ((&JOBTYPE = 'M') *OR (&JOBTYPE = 'R') + 
*OR (&JOBTYPE = 'S') *OR (&JOBTYPE = 'W') oh 
*OR (&JOBTYPE = 'X')) + 


spool reader, system job, 


THEN (GOTO CMDLBL(ENDLOOP) ) 


convert to decimal, 
and if request run priority is less than or equal to the current 
run priority then loop to next job. 


VAR (&RUNPTY4) 


&RUNPTY8 


VAR (&RUNPTY5) 
COND (&RUNPTY5 


convert to decimal 5,0, 


VALUE (%SST(&JOBI 65 4)) 
SBINARY (&RUNPTY4) 

VALUE (&RUNPTY8) 
*GE &RUNPTY) HEN (GOTO + 


CMDLBL (ENDLOOP) ) 


convert to run priority to character, 
the job run priority and seen message stating the run priority 
was changed. 


VAR (&RJOB) 
VAR (&RUSER) 
VAR (&RNBR) 
VAR ( 
VAR ( 


&RUNPTYC) 
&RUNPTY5C) 


change 


VALUE (SSST(&JOBI 9 10)) 
VALUE (%SST(&JOBI 19 10)) 
VALUE (SSST(&JOBI 29 6)) 
VALUE (&RUNPTY) 

VALUE (&RUNPTY5) 


ey 
“/ 


CHGJOB JOB (&RNBR/&RUSER/&RJOB) RUNPTY (&RUNPTYC) 

MONMSG MSGID (CPF1343) EXEC (GOTO CMDLBL(ENDLOOP) ) 

SNDPGMMSG MSG('Job' *BCAT &RNBR *TCAT '/' *TCAT + 
&RUSER *TCAT '/' *TCAT &RJOB *BCAT ‘run + 
priority was change from' *BCAT &RUNPTY5C + 
*BCAT 'to' *BCAT &RUNPTYC *TCAT '."') 


va bar A 
/* At end of loop set new decimal position to next entry and af 
/* decrement loop counter by one. ‘a 
es ef 
ENDLOOP: CHGVAR VAR(&DEC8) VALUE (&DEC8 + &ELEN) 

CHGVAR VAR(&LOOP) VALUE (&LOOP —- 1) 

GOTO CMDLBL(STARTLOOP ) 
7% a / 
/* Send message that no jobs were found. ha 
es if 
NOJOBS: SNDPGMMSG MSG('No jobs found."') 
/* */f 
/* All done. Now delete temporary user space that we created. eee 
has otf 
ALLDONE: DLTUSRSPC USRSPC (QTEMP/&EUSRSPC) 

MONMSG CPFO0000 

ENDPGM 


The program can be changed to change the run priority by removing the IF statement to compare the current and requested run 
priority. 


To create the CL program, specify the following: 


CRTCLPGM PGM(QGPL/CHGACTJOB) SRCFILE (QGPL/QCLSRC) 


You can change the command to: 


e Specify a different printer device. 


Specify a different output queue. 


Specify different job attributes that the Change Job (CHGJOB) command can change. 


List only jobs on an output queue and remove the spooled files. 


e Provide a menu to select jobs to be changed. 


Changing a Job Schedule Entry 


This command interface to the Change Job Schedule Entry User (CHGSCDEUSR) program can change the USER parameter in the 
job schedule entry. You may: 


e Specify a job schedule entry name 
e Specify a generic job schedule entry name 


e Specify the *ALL value 


This example uses the following APIs: 
e Create User Space (QUSCRTUS) 


e List Job Schedule Entries (QWCLSCDE) 


e Retrieve User Space (QUSRTVUS) 


The following is the command definition for the CHGSCDEUSR command: 


CMD PROMPT ('Change Job Schedule Entry User') 
/* CPP CHGSCDEUSR */ 
PARM KWD (JOB) TYPE(*GENERIC) LEN(10) + 


SPCVAL((*ALL)) + 
MIN(1) PROMPT('Job name:') 


PARM KWD (OLDUSER) YPE(*NAME) LEN(10) + 
MIN(1) PROMPT('Old user name:"') 
PARM KWD (NEWUSER) YPE(*NAME) LEN(10) + 


MIN(1) PROMPT('New user name:') 


To create the command, specify the following: 


CRTCMD CMD (QGPL/CHGSCDEUSR) PGM(QGPL/CHGSCDEUSR) + 
SRCF ILE (QGPL/QCMDSRC) 


The following is the command-processing program that is written in CL to list the job schedule entries and change the user if 
necessary: 


/* KK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KK KK x/ 


/* PROGRAM: CHGSCDEUSR */ 
Ve */ 
/* LANGUAGE: CL Af 
[ce */ 
/* DESCRIPTION: THIS PROGRAM WILL CHANGE THE USER FOR A LIST OF */ 
[% JOB SCHEDULE ENTRIES. As /; 
es ¥. 
/* APIs USED: QUSCRTUS, QWCLSCDE, QUSRTVUS */ 
[% */ 
/* KK KKK KKK KK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKKKKKKKKKKKKKK x/ 
PGM PARM (&JOBNAME &OLDUSER &NEWUSER) 
i */ 
/* Input parameters are as follows: ‘a 
i Kf 
DCL VAR(&JOBNAME) TYPE(*CHAR) LEN(10) /* Input + 
job name */ 
DCL VAR(&OLDUSER) TYPE(*CHAR) LEN(10) /* Input + 
old user name */ 
DCL VAR(&NEWUSER) TYPE(*CHAR) LEN(10) /* Input + 


new user name */ 


/* */ 
/* Local variables are as follows: */ 
/* */ 
DCL VAR(&USRSPC) TYPE(*CHAR) LEN(20) + 
VALUE ('CHGSCDEUSROTEMP ') /* User + 
space name for APIs */ 
DCL VAR(&CNTHDL) TYPE(*CHAR) LEN(16) + 
VALUE (' ') /* Continuation + 
handle */ 
DCL VAR(&NUMENTB) TYPE(*CHAR) LEN(4) /* Number + 
of entries from list job schedule entries + 
in binary form */ 
DCL VAR(&NUMENT) TYPE(*DEC) LEN(8 0) /* Number + 


of entries from list job schedule entries + 
in decimal form */ 
DCL VAR(&HDROFFB) TYPE(*CHAR) LEN(4) /* Offset + 

to the header portion of the user space in + 


DCL 


DCL 


DCL 


DCL 


DCL 


DCL 


DCL 


DCL 


DCL 


DCL 


DCL 


DCL 


Start of code 


VA 


VA 


VA 


VA 


VA 


VA 


VA 


VA 


VA 


VA 


VA 


VA 


binary form */ 


binary form */ 


binary form */ 


area for job name */ 


area for entry number */ 


area for user name */ 


R(&GENHDR) TYPE(*CHAR) LEN(140) /* Generic + 
header information from the user space */ 
R(&HDRINFO) TYPE(*CHAR) LEN(26) /* Header + 
information from the user space */ 
R(&LSTSTS) TYPE(*CHAR) LEN(1) /* Status + 
of the list in the user space */ 
R(&OFFSETB) TYPE(*CHAR) LEN(4) /* Offset 4 
to the list portion of the user space in + 


R(&HDRLENB) TYPE(*CHAR) LEN(4) /* Length + 
to the header portion of the user space in + 


R(&STRPOSB) TYPE(*CHAR) LEN(4) /* Starting + 
position in the user space in binary form */ 
R(&ELENB) TYPE(*CHAR) LEN(4) /* List job + 
entry length in binary 4 form */ 

R(&LENTRY) TYPE(*CHAR) LEN(1156) /* + 
Retrieve area for list job schedule entry */ 
R(&INFOSTS) TYPE(*CHAR) LEN(1) /* Retrieve + 
area for information status */ 
R(&JOBNAM) TYPE(*CHAR) LEN(10) /* Retrieve + 


R(&ENTRY#) TYPE(*CHAR) LEN(6) /* Retrieve + 


R(&USERNM) TYPE(*CHAR) LEN(10) /* Retrieve + 


You may want to monitor for additional messages here. ‘an 


This creates the user space. 


The user space will be 256 bytes ef 


/* and will be initialized to blanks. *f 
[% */ 
CALL PGM(QUSCRTUS) PARM(&USRSPC 'CHGSCDEUSR! + 
X'00000100' ' ' '*ALL ' '"CHGSCDEUSR + 
TEMPORARY USER SPACE *) 
MONMSG MSGID (CPF3C00) EXEC (GOTO CMDLBL (ERROR) ) 
[* * 
/* This lists job schedule entries of the name specified. */ 
/F */ 
PARTLIST: CALL PGM(QWCLSCDE) PARM(&USRSPC 'SCDLO200' + 
&JOBNAME &CNTHDL 0) 
7% es 
/* Retrieve the generic header from the user space. %f 
es */ 
CALL PGM(QUSRTVUS) PARM(&USRSPC X'O00000001' + 
X'0000008C' &GENHDR) 
MONMSG MSGID (CPF3C00) EXEC (GOTO CMDLBL (ERROR) ) 
fe bay 
/* Get the information status for the list from the generic header. */ 
/* If it is incomplete, go to BADLIST label and send out 'Bad list' */ 
/* message. */ 
/* */ 


CHGVAR 


VA 


R(&LSTSTS) VALUE (%SST(&GENHDR 104 1)) 


IF COND (&LSTSTS = 'I') THEN(GOTO CMDLBL(BADLIST) ) 


/* *f. 
/* Get the number of entries returned. Convert to decimal and * 
/* if zero go to NOENTS label to send out 'No entries' message. */ 
/* */ 
CHGVAR VAR(&NUMENTB) VALUE(%SST(&GENHDR 133 4)) 
CHGVAR VAR (&NUMENT) VALUE (SBIN (&NUMENTB) ) 
IF COND (&NUMENT = 0) THEN(GOTO CMDLBL (NOENTS) ) 
aa * 
/* Get the list entry length and the list entry offset. */ 
/* These values are used to set up the starting position. */ 
pr *f 
CHGVAR VAR(&ELENB) VALUE (%SST(&GENHDR 137 4) ) 
CHGVAR VAR(&OFFSETB) VALUE(%SST(&GENHDR 125 4)) 
CHGVAR VAR(SBIN(&STRPOSB) ) VALUE (%SBIN(&OFFSETB) + 1) 
[* */ 
/* This loops for the number of entries until no more entries are */ 
/* found and goes to the ALLDONE label. es 
ie */ 
STARTLOOP: IF COND (&NUMENT = 0) THEN(GOTO CMDLBL(PARTCHK) ) 
[* *f 
/* This retrieves the list entry. */ 
SF */ 
CALL PGM(QUSRTVUS) PARM(&USRSPC &STRPOSB &ELENB + 
&LENTRY) 
MONMSG MSGID (CPF3C00) EXEC (GOTO CMDLBL (ERROR) ) 
[F *f 
/* This copies the information status, job name, entry number, and */ 
/* user name. */ 
fF HY: 
CHGVAR VAR(&INFOSTS) VALUE(%SST(&LENTRY 1 1) ) 
CHGVAR VAR (& JOBNAM) VALUE (SSST(&LENTRY 2 10) ) 
CHGVAR VAR (& ENTRY#) VALUE (S$SST(&LENTRY 12 10)) 
CHGVAR VAR (& USERNM) VALUE (SSST(&LENTRY 547 10) ) 
hes */ 
/* This checks to make sure the list entry contains the user name. */ 
/* If it does, the user name is compared to the old user name *f 
/* passed in. If either of these checks fails, this entry will */ 
/* be skipped. */ 
/* */ 
IF COND (&INFOSTS *NE ' ') THEN(GOTO + 
CMDLBL (ENDLOOP) ) 
IF COND (&USERNM *NE &OLDUSER) THEN(GOTO + 
CMDLBL (ENDLOOP) ) 
Le */ 
/* This code will issue the CHGJOBSCDE command for the entry. *f 
ya ef 
CHGJOBSCDE JOB(&JOBNAM) ENTRYNBR(&ENTRY#) USER (&NEWUSER) 
MONMSG MSGID (CPF1620) EXEC (GOTO CMDLBL (NOCHG) ) 
SNDPGMMSG MSG('Entry' *BCAT &JOBNAM *BCAT &ENTRY# + 
*BCAT 'was changed.') 
GOTO CMDLBL (ENDLOOP) 
NOCHG: SNDPGMMSG MSG('Entry' *BCAT &JOBNAM *BCAT &ENTRY# + 
*BCAT 'was NOT changed."') 


/* At end of loop, 


ENDLOOP : 


CHGVAR 


CHGVAR 
GOTO 


set new decimal position to the next entry and 
/* decrement the loop counter by one. 


VAR (SBIN (&STRPOSB) ) 


+ SBIN(&ELENB) ) 


VALUE (%BIN(&STRPOSB) + 


VAR(&NUMENT) VALUE (&NUMENT —- 1) 


CMDLBL (STARTLOOP 


) 


/* This sends a message that no entries were found. 


NOENTS: 


/* 


SNDPGMMSG MSG('No entries found.') 


GOTO 


CMDLBL (ALLDONE) 


/* This sends a message that the list was incomplete. 


/* 


BADLIST: 


SNDPGMMSG MSG('Incomplete list in the user space. + 
See joblog for details.') 


GOTO 


CMDLBL (ALLDONE) 


/* This sends a message that an unexpected error occurred. 


/* 


SNDPGMMSG MSG('Unexpected error. 
See joblog for details.') 


GOTO 


CMDLBL (ALLDONE) 


+ 


/* This will check for a partial list in the user space and 
/* finish processing the rest of the list. 


/* 

PARTCHK: 

/* 

/* Retrieve 


/* Use this 
/* 


/* All done. 


ALLDONE: 


IF 


COND (&LSTSTS = 'C') 


the header information from the user space. 
information to get the rest of the list. 


CHGVAR 
CHGVAR 
CALL 


MONMSG 
CHGVAR 
GOTO 


VAR(&HDROFFB) VA 
VAR(&HDRLENB) VA 
PGM(QUSRTVUS) PA 


&HDRLENB &HDRINFO) 
MSGID (CPF3C00) EXEC (GOT 


VAR(&CNTHDL) VAL 
CMDLBL (PARTLIST) 


UE (%SS1 


LUE (%SST(&GENHDR 121 4)) 
LUE (%SST(&GENHDR 117 4)) 
RM(&USRSPC &HDROFFB + 


[TO CMDLBL (ERROR) ) 
[(&HDRINFO 11 16)) 


Now the temporary user space is deleted. 


DLTUSRSPC USRSPC(QTEMP/%SST(&USRSPC 1 10)) 


MONMSG 
ENDPGM 


MSGID (CPF0000) 


To create the CL program, specify the following: 


CRTCLPGM PGM (QGPL/CHGSCDEUSR) 


You can change the command to: 


SRCFILE (QGPL/QCLSRC) 


Rf. 
sh 


* 
*/ 


Tif 
ei] 


fe 
ef 


THEN (GOTO CMDLBL(ALLDONE) ) 


sh 
xy 


e Specify different parameters that the Change Job Schedule Entry (CHGJOBSCDE) command can change. 


e Provide a menu to select job schedule entries to be changed. 


Creating Your Own Telephone Directory 


To create a telephone directory, you must use the following $USIDXCRT ILE C program to create a user index, and you must use the 
$USIDXEX ILE C program to insert the entries into a telephone directory. 


To set up the program to create a user index, specify the following: 


[KKK KK KK KKK IK IA AA IA IA I A A AA A A A I a I I / 


/* PROGRAM: SUSIDXCRT Rif 
/* * / 
/* LANGUAGE: ILE C for OS/400 */ 
vs */ 
/* DESCRIPTION: THIS PROGRAM CREATES A USER INDEX NAMED "TESTIDX" */ 
/* IN THE LIBRARY "QGPL". * / 
/* * / 
/* APIs USED: QUSCRTUI */ 
/* xf 


[KK RK KKK KK KK KK IK IA IA IA I A AAA A IA A I I I / 


#include <quscrtui.h> 
main () 
{ 


[KK RK KK KK KK KK IR IA AA IA I I A AAA AA A I A I / 


/* Set up the parameters to be used in the call to 'QUSCRTUI' * / 
[¥ OK KK KKK KK KK KKK I A IA AA IA I I A AA AAA A A a I I / 
char idx_name[]= "TESTIDX QGPL Mee 

char ext_atr[]= "TESTER ee 

char entry_lgth_att[] = "F"; 

int entry_lngth = 50; 

char key_insert[] = "1"; 

int key_lngth = 15; 

char imm_update[] = "0"; 

char optim[] = "0"; 

char auth[] = "*CHANGE We 

char desc[] = "Description ..... Mes 

[OK KK KK KK KKK KK IA IA IA IA I I A AA AA IA A A I a I I / 


/* Call the 'QUSCRTUI' program to create the user index. vA 


[KOK KK KK KKK KK KKK IA IA IA IA I I A AAA IA A IA I a I a / 


QUSCRTUI (idx_name, ext_atr,entry_lgth_att,entry_lngth,key_insert, 
key_lngth, imm_update, optim, auth, desc) ; 
} 


To compile the program that creates the user index, specify the following: 


CRTBNDC PGM(QGPL/SUSIDXCRT) SRCFILE(QGPL/QCSRC) 


To insert entries into the user index, use the following ILE C program: 


[KKK KK KK KKK KK IK IA AA IA I I A AA AA AA A A I I  / 


/* PROGRAM: SUSIDXEX mf, 
/* */ 
/* LANGUAGE: ILE C for OS/400 AY 
br */ 
/* DESCRIPTION: THIS PROGRAM USES A USER INDEX TO KEEP TRACK OF Rf 
/* NAMES AND PHONE NUMBERS. THERE ARE TWO OPERATIONS THAT ARE */ 
fe DEMONSTRATED IN THIS EXAMPLE. THE FIRST IS THE INSERTION OF */ 
/* AN ENTRY INTO THE INDEX, AND SECONDLY THE FINDING OF A GIVEN */ 
/* INDEX ENTRY. ay 
/* THE INDEX IS KEYED ON THE LAST NAME, THEREFORE ENTER AS MUCH */ 
/* OF THE NAME AS YOU KNOW AND THE PROGRAM WILL LIST ALL ENTRIES */ 


/* MATCHING YOUR STRING (IN ALPHABETICAL ORDER) . ay A 


/* a 
/* APIs USED: NONE *f 
/* * / 


[ORK RK KK KK KKK KR IR AA IA IA A AAA AAA AA A A a I A / 


#include <stdio.h> 
#include <string.h> 
#include <miindex.h> 
#include <miptrnam.h> 
#include <stdlib.h> 
#include <ctype.h> 


_SYSPTR index; 

_IIX_Opt_List_T ins_option_list; 
_IIX_Opt_List_T *fnd_option_list; 

char Name_And_Num[50]; 

char In_Name[50]; 

char Out_Num[5000]; 

char response[1]; 

char name[35]; 

char number[15]; 

int Ent_Found, count, start, length_of_entry; 


[ORK RK KK KKK KK KK KK IA AA A I I A AA AA A A A I I I a / 


/* Procedure to copy 'cpylngth' elements of 'string2' into the oid 
/* new string, 'stringl'; starting at position 'strpos'. Ref 
[KK RK KK KKK KK KK IK AA IA A I I A AA AAA AAA A I / 


void strncpyn(stringl, string2,strpos, cpylngth) 
char stringl[],string2[]; 
int strpos,cpylngth; 
{ 
int x = 0; 
while (x < cpylngth) 
stringl [x++]=string2[strpost+t+]; 
} /*strncpyn*/ 


[OK KK KK KK KK KK KA IA IA A I I A AA AA AA A AA I a I A / 


/* Procedure to convert any string into uppercase, where applicable */ 
[ORK RK KK KKK KKK KK IR IA AA A I A AAA AA A A I 


void convert_case(stringl) 

char stringl[]; 

{ 

int x = 0; 

while (x < (strlen(stringl))) { 
stringl[x] = toupper(stringl[x]); 
xt+; 

} /*while*/ 

} /*convert_case*/ 


main () 

{ 

fnd_option_list = malloc(sizeof (_IIX_Opt_List_T 
+99* sizeof (_IIX_Entry_T 


— 


~~ 


; 


[ORK RK KK KK KK KKK IA AA IA A I A AA AAA AA A A I a Ie A / 


/* Resolve to the index created in S$USIDXCRT. */ 
[ORK RK KK KKK KK KKK IA IA AA IA AA AA AA A A a / 


index = rslvsp(_Usridx, "TESTIDX", "OQGPL", _AUTH_ALL) ; 


[ORK RK KK KKK KK KK IK AA IA A I AA A AA AA A A I / 


/* Set up the insert option list Pop, 


[OK KK KK KK KK I IK IA IA A I AAA AAA A A a I a / 


ins_option_list.Rule = _INSERT_REPLACE; 
ins_option_list.Arg_Length = 50; 
ins_option_list.Occ_Count = 1; 


ins_option_list.Entry[0].Entry_Length 503 
ins_option_list.Entry[0].Entry_Offset = 0; 


[ORK RK KR KK KK KKK IK IA IA IA I I A AA AAA AA A A I I I I / 


/* Set up the find option list aif 


[ORK RK KK KKK KK KK IA IA IA IA I I AAA A A A A I I I / 


fnd_option_list->Rule = _FIND_EQUALS; 
fnd_option_list-—>Occ_Count = 100; 


[KKK KK KKK KK KK IK IR IA IA I A AA A AA A A a 


/* Loop until the choice 'Q' is entered at the menu */ 
[ORK RK KK KK KK KKK IR IA IA IA I A AA AA A A I I I / 


while (1==1) { 


PLANts (TA N\Nn* eR KAA AERR RR AAAKKERRR EV) F 
printf ("* TELEPHONE INDEX a\nt)3 
PLANCE (TX KARAKKKKKKKRAEKEKK KEKE NM) » 
printf("* 'A' Add name & num *\n"); 
printf("* 'L' List a number *\n"); 
printf("* "OQ" Quit index *\n"); 

) 


PLANE (TX KRRRR KAKA EREEEKKE\ DM 


e 
gets (response) ; 
if ((strncmp (response, "A",1)== ) || (strncemp (response, "a", 1)== )) 
{ printf("\nEnter name to add. ex(Last, First) \n"); 
gets (name) ; 
convert_case (name) ; 
printf ("\nEnter number to add. ex(999-9999) \n"); 
gets (number) ; 
strcpy (name, strcat (name, " er 
strcpy (Name_And_Num, strcat (name, number) ) ; 
printf("\nName and number to add is => %s\n",Name_And_Num) ; 
insinxen (index, Name_And_Num, Integrated Netfinity Server_option_list); 
} /* if 'al*/ 
if ((strncmp (response, "L",1)== ) || (strncemp (response, "1",1)== )) 


printf ("\nEnter name to find. ex(Last, First) \n"); 
gets (In_Name) ; 
convert_case (In_Name) ; 
fnd_option_list-—>Arg_Length = strlen(In_Name) ; 
fndinxen (Out_Num, index, fnd_option_list, In_Name) ; 
length_of_entry = fnd_option_list-—>Entry[0].Entry_Length; 
Ent_Found = fnd_option_list-—>Ret_Count; 
if (Ent_Found == 0) 

printf("\nName not found in index => %s\n",In_Name) ; 
else { 

if (Ent_Found > 1) { 


printf ("\n%d occurences found, \n",Ent_Found) ; 
count = 0; 

start = 0; 

while (count++ < Ent_Found) { 

printf("Name and number is => %s\n",Out_Num) ; 


start = start + length_of_entry; 
strncpyn (Out_Num, Out_Num, start, length_of_entry) ; 
} /* while */ 
}else 
printf("\nName and number is => %s\n",Out_Num) ; 
} /*else*/ 
} J/*if i ea 
if ((strncmp (response,"Q",1)== ) || (strnemp (response, "q",1)== )) 
{ break; } 
} /*while*/ 


} /*SUSIDXEX*/ 


To create the ILE C program to insert entries into the user index, specify the following: 


CRTBNDC PGM(QGPL/SUSIDXEX) SRCFILE (QGPL/QCSRC) 


Creating and Manipulating a User Index 


The following example shows how to create and manipulate a user index with a call from an MI program. For another example using 
the QUSCRTUI API, see Creating Your Own Telephone Directory. 


[ORK RK KK KK KKK KK IA AA IA IA I I A AAA AAA A A I A / 


/* * / 
/* PROGRAM: GLOBALV zy, 
/* * / 
/* LANGUAGE: MI/IRP af 
/* * / 
/* DESCRIPTION: MAINTAINS AN INDEPENDENT INDEX. EACH INDEX ENTRY */ 
[* CONTAINS 100 BYTES OF USER DATA. THE ENTRIES ARE */ 
/* KEYED TWO 10 BYTE VALUES: THE USER PROFILE AND A */ 
/* VALUE IDENTIFIER. */ 
/* * / 
/* APIs USED: QUSCRTUI */ 
/* a 
/* PARAMETERS: */ 
/* * / 
/* PARM TYPE DESCRIPTION */ 
/* */ 
/* 1 CHAR (1) FUNCTION: */ 
[* aay | 
/* 'U': UPDATE GLOBALV INFORMATION */ 
/* "R': RETRIEVE GLOBALV INFORMATION ia 
/* * / 
/* 2 CHAR (10) USER PROFILE zy 
/* */ 
/* THE NAME OF THE USER PROFILE FOR WHICH */ 
/* INFORMATION IS TO BE SAVED OR RETRIEVED. */ 
[* * / 
hei 3 CHAR (10) VALUE ID */ 
Vs a 
/* THE NAME OF THE GLOBALV VARIABLE ID FOR WHICH */ 
/* INFORMATION IS TO BE SAVED OR RETRIEVED. ia 
/* a 
/* 4 CHAR(100) VALUE */ 
/* * / 
/* IF FUNCTION IS 'U', THIS VALUE SHOULD CONTAIN */ 
/* THE NEW VALUE TO BE ASSOCIATED WITH THE */ 
/* USER ID AND VALUE ID. */ 
/* * / 
/* IF FUNCTION IS 'R', THIS VARIABLE WILL BE * / 
/* SET TO THE VALUE ASSOCIATED WITH THE USER ID */ 
/* AND VALUE ID. IF NO VALUE EXISTS, *NONE */ 
/* IS SPECIFIED. zy 
/* */ 


[OK KK KK KK KK KK IK IA IA IA I I A A AA AA IA aA I I A / 


ENTRY * (GLOBALV_PARM) EXT; 


[ROKK RK KK KK KK KK IR IA IA IA I A AAA A AA A A I A / 


/* PARAMETER VALUE POINTERS FOR GLOBALV. */ 


[ORK RK KK KK KKK KK IK IA IA IA I I I I AA AA AIR AA IA A I He a / 


DCL SPCPTR GV_REQUEST@ PARM; 
DCL SPCPTR GV_USERID@ PARM; 


DCL SPCPTR GV_VALUEID@ PARM; 
DCL SPCPTR GV_VALUE@ PARM; 


[OK KK KK KK KK KKK IR IA IA A I I A A AA AAA AA A A I I I a / 


/* PARAMETER VALUES FOR GLOBALV. 


«/ 


[KK RK KK KK KK KKK IA IA AA IA I A AAA AA A A I I I A / 


DCL DD GV_REQUEST CHAR(1) BAS (GV_REQUEST®) ; 
DCL DD GV_USERID CHAR(10) BAS (GV_USERID@) ; 
DCL DD GV_VALUEID CHAR(10) BAS (GV_VALUEID®@) ; 
DCL DD GV_VALUE CHAR(100) BAS (GV_VALUE®@) ; 


[ORK RK KK KK KK KK KK AA IA A A A AA AA A A a I A / 


/* PARAMETER LIST FOR GLOBALV. 


Be 


[ORK RK KK KK KK KK IR AA AA A I A AA AAA A A A a oe a / 


DCL OL GLOBALV_PARM (GV_REQUEST®@ 
, GV_USERID@ 
,GV_VALUEID®@ 
, GV_VALUE@ 
) PARM EXT; 


[OK KK KK KK KK KK IA AA AA A I I AAA AAA A A A I / 


(QUSCRTUIL) API. EA 


[ORK RK KK KKK KK KK IA IA IA IA I AA A A A IA A I He A / 


QGPL ")i 


me 


*)y 


oe 


[OK KK KK KK KKK IK IR IA IA IA I A AA AA AA A A a I a / 


/* POINTERS TO ARGUMENT VALUES FOR QUSCRTUI API. */ 


[KKK KK KKK KK KKK IR IA AA IA I I A A AA AAA AA A A I I I / 


[OR KK KKK KK KK KK IK AA IA A I A AA AAA AA A A I / 


/* ARGUMENT VALUES FOR CREATE USER INDEX 
DCL DD UI_NAME CHAR(20) INIT ("GLOBALV 
DCL DD UI_ATTR CHAR(10) INIT(" 
DCL DD UI_EATR CHAR(1) INIT("EF"); 
DCL DD UI_ELEN BIN(4) INIT(120); 
DCL DD UI_KATR CHAR(1) INIT("1"); 
DCL DD UI_KLEN BIN(4) INIT(20); 
DCL DD UI_IUPD CHAR(1) INIT("0"); 
DCL DD UI_OPT CHAR(1) INIT("0"); 
DCL DD UI_AUT CHAR(10) INIT ("*CHANGE 
DCL DD UI_TEXT CHAR(50) 

INIT ("GLOBALV INDEX 
DCL SPCPTR UI_NAME@ INIT (UI_NAMBE) ; 
DCL SPCPTR UI_ATTR@ INIT(UI_ATTR) ; 
DCL SPCPTR UI_EATR@ INIT(UI_EATR) ; 
DCL SPCPTR UI_ELEN@ INIT (UI_ELEN) ; 
DCL SPCPTR UI_KATR@ INIT(UI_KATR) ; 
DCL SPCPTR UI_KLEN@ INIT (UI_KLEN) ; 
DCL SPCPTR UI_IUPD@ INIT(UI_IUPD) ; 
DCL SPCPTR UI_OPT@ INIT(UI_OPT); 
DCL SPCPTR UI_AUT@ INIT(UI_AUT); 
DCL SPCPTR UI_TEXT@ INIT (UI_TEXT) ; 
/* ARGUMENT LIST FOR QUSCRTUI API. 


aaa 


[ORK RK KK KKK KK KK KK AA IA IA I I A AA AA AA A A a He A / 


DCL OL QUSCRTUI_ARG (UI_NAME@ 
, UI_ATTR@ 
, UI_EATR@ 
, UI_ELEN@ 
, UI_KATR@ 
, UI_KLEN@ 
, UI_IUPD@ 
,UI_OPT@ 
,UI_AUT@ 
, UI_TEXT@ 


) ARG; 


[KK RK KKK KK KK KK IA AA IA A I AAA A A A a I A / 


/* SYTSEM POINTER TO QUSCRTUI API *PGM OBJECT. */ 


[KOK KK KR KK KK KKK IR IA IA IA I I A AA AAA AA IA A A Ie A / 


DCL SYSPTR QUSCRIUI INIT("QUSCRTUI", TYPE (PGM) ); 


[RK RK KK KKK KK KK A IA IA IA I AAA AA A A a I I / 


/* SYSTEM POINTER TO GLOBALV *USRIDX OBJECT. aif 


[ORK RK KKK KK KK KK KK IA IA A I A A AA AA A A I I I / 


DCL SYSPTR INX@; 


DCL DD INX_OBJECTID CHAR(34); 

DCL DD INX_OBJECTID_TYPE CHAR(2) DEF (INX_OBJECTID) POS(1) 

INIT (X'OEOA') ; 

DCL DD INX_OBJECTID_NAME CHAR(30) DEF (INX_OBJECTID) POS (3) 

INIT ('GLOBALV hd er 

DCL DD INX_OBJECTID_AUT CHAR(2) DEF (INX_OBJECTID) POS (33) 
INIT (X'0000'); 


[ORK RK KK KKK KK KK IK AA AA A I A AAA AA A AA A a A / 


/* EXCEPTION MONITOR TO DETECT 2201X EXCEPTIONS (OBJECT NOT FOUND) */ 


[ORK RK KKK KK KK KK IK IA IA A I I I A AAA AA A A a I / 


DCL EXCM EXCM_NOOBJECT EXCID(H"2201") INT(CREATE_INDEX) IMD; 


[ORK RK KK KK KK KKK KA AA IA IA I A AAA AA A A I I / 


/* PASA INVOCATION ENTRY FOR RETURN FROM EXCEPTION. */ 


[ORK RK KKK KK KKK KK IA AA AA A I A AAA A A A I A / 


DCL DD RTN_NOOBJECT CHAR(18) BDRY (16); 

DCL SPCPTR RTN_NOOBJECT@ INIT (RTN_NOOBJECT) ; 

DCL DD RTN_NOOBJECT_ADDR CHAR(16) DEF (RTN_NOOBJECT) ; 

DCL DD RTN_NOOBJECT_OPT CHAR(1) DEF (RTN_NOOBJECT) POS (18) 
INIT (X'00'); 


[KKK RK KK KKK KK IK IK IA IA A I I A AA AA A A I I / 


/* RECEIVER VARIABLE FOR INDEPENDENT INDEX OPERATIONS. * / 


[KK RK KK KKK KK KK IR IK IA IA A A AAA AA A A I I I I / 


DCL DD INX_RECEIVER CHAR(120) ; 
DCL SPCPTR INX_RECEIVER@ INIT (INX_RECEIVER) ; 


[ORK RK KK KK KK KK IR AA IA IA A AAA AA AA A A I I I / 


/* OPTION TEMPLATE FOR INDEPENDENT INDEX OPERATIONS. */ 
[BOR KK KK KKK KK KK IR AA IA IA I I A AAA A AA A A a I I / 
DCL DD INX_OPT CHAR(14); 

DCL SPCPTR INX_OPT@ INIT(INX_OPT) ; 

DCL SPC INX_OPT_SPC BAS (INX_OPT®@) ; 

DCL DD INX_OPT_RULE CHAR(2) DIR; 

DCL DD INX_OPT_ARGL BIN(2) DIR; 

DCL DD INX_OPT_ARGO BIN(2) DIR; 

DCL DD INX_OPT_OCCC BIN(2) DIR; 

DCL DD INX_OPT_RTNC BIN(2) DIR; 

DCL DD INX_OPT_ELEN BIN(2) DIR; 

DCL DD INX_OPT_EOFF BIN(2) DIR; 

[ORK RK KK KKK KKK IK IA AA AA A I A AA A IA A I I 
/* ARGUMENT VARIABLE FOR INDEPENDENT INDEX OPERATIONS. af 
[ORK RK KK KKK KK IK IR IA A AA I A AA AA A A A a I / 
DCL DD INX_ARG CHAR(120); 


DCL SPCPTR INX_ARG@ INIT (INX_ARG) ; 


[ORK RK KK KK KK KKK IA IR IA A I I A AA AAA A A A a I / 


/* START OF CODE 


[OK KK KKK KK KK KR IA IA IA A I A A AA AA AA IA A a I a / 


MATINVE RIN_NOOBJECT_ADDR, *,X'03 


RSLVSP INX@, INX_OBJECTID,*,*; /* 
/* 


CMPBLA(B) GV_REQUEST, 'U'/NEQ(NOT_UPDATE); /* IF GV_REQUEST 7= U 


/* SET UP OPTIONS FOR INSERT INDEPENDENT INDEX ENTRY (INSINXEN) 


/* OPERATION. 


CPYBLA INX_OPT_RULE,X'0002'; 
CPYNV INX_OPT_OCCC,1; 


CPYBLA INX_ARG(1:10),GV_USERID; /* SPECIFY INDEX ENTRY. 
CPYBLA INX_ARG (11:10) ,GV_VALUEID; 

CPYBLA INX_ARG(21:100) ,GV_VALUE; 
INSINXEN INX@, INX_ARG@, INX_OPT@; /* IN 


RTX *; 


NOT_UPDATE: 


CMPBLA(B) GV_REQUEST, 'R'/NEQ(NOT_RETRIEVE); /* IF GV_REQUEST 7= R 


/* SET UP OPTIONS FOR FIND INDEPENDENT INDEX ENTRY (FNDINXEN) 


/* OPERATION. 


CPYBLA INX_OPT_RULE,X'0001'; 
CPYNV INX_OPT_ARGL, 20; 
CPYNV INX_OPT_OCCC,1; 


CPYBLA INX_ARG(1:10),GV_USERID; /* SPECIFY SEARCH ARGUMENT. 


CPYBLA INX_ARG (11:10) ,GV_VALUEID; 
FNDINXEN INX_RECEIVER@, INX@, INX_OPT@, INX_ARG@; /* FIND ENTRY. 


CMPNV(B) INX_OPT_RTNC, 1/EQ (FOUND_ENTRY 


CPYBLAP GV_VALUE,'*NONE',' ' 
RTX *; 


FOUND_ENTRY: 


CPYBLA GV_VALUE, INX_RECEIVER(21:100); /* ENTRY WAS FOUND, 


RTX *; 
NOT_RETRIEVE: 


RTX *; /* UNKNOWN FUNCTION CODE. 


*/ 

', /* MATERIALIZE THIS PROGRAM'S */ 
/* INVOCATION ENTRY IN THE */ 
/* PASA. THIS ENTRY IS USED */f 
/* WHEN RETURNING FROM THE * / 
/* EXCEPTION HANDLER BELOW. * / 
RESOLVE TO "GLOBALV" USER INDEX */ 
OBJEC IF THE OBJECT DOES NO Bf 
EXIST, THEN THE X'2201' EXCEPTION*/ 
IS RETURNED, CAUSING THE "OBJECT */ 
NOT FOUND" EXCEPTION HANDLER AT */ 
THE END OF THE PROGRAM TO RUN. */ 
*/ 

/* BRANCH TO NOT_UPDATE */ 

a7, 

=), 

/* RULE= INSERT. */ 
/* OCCURRENCE COUNT = 1. Ref 
*/ 

SERT THE INDEX ENTRY. ay, 

/* RETURN Ff, 
*/ 

/* GOTO NOT_RETRIEVE. */ 

*/ 

*/ 

/* RULE= FIND WITH EQUAL KEY. */ 
/* ARGUMENT LENGTH= 20. aid 
/* OCCURRENCE COUNT=1. ay A 
*/ 

vA 

); /* IF RETURN_COUNT = 1 */ 

/* GOTO FOUND_ENTRY. */ 

; /* ENTRY WAS NOT FOUND, SPECIFY */ 
/* VALUE OF *NONE. */ 
/* RETURN #Yy: 
*/ 

/* COPY VALUE TO USER */ 

/* PARAMETER. mf 

/* RETURN */ 

RETURN. */ 


[¥ ORK RK KK KK KK KKK IR AA AA A I A AA AA AA A A I I I / 


/* “OBJECT NOT FOUND" EXCEPTION HANDLER. 


[KKK KK KK KK KK KK IK IR IA IA I I A AAA AA IA A a I I / 


aa 


ENTRY CREATE_INDEX INT; 


MODEXCPD EXCM_NOOBJECT, X'0000',X'0O1'; /* TURN OFF EXCEPTION * / 
/* MONITOR. */ 


CALLX QUSCRTUI, QUSCRTUI_ARG,*; /* USE QUSCRTUI API TO CREATE THE */ 
/* USER INDEX OBJECT. */ 


RINEXCP RTN_NOOBJECT@; /* RETURN FROM THE EXCEPTION HANDLER AND */ 
/* RETRY THE OPERATION. */ 


PEND; 


Creating a Batch Machine 


These ILE C programs emulate a batch machine. One program, $USQEXSRV, acts as a server and takes the entries off a user queue 
and then runs the request through the Execute Command (QCMDEXC) API. The other program, $USQEXREQ, acts as a requester 
and puts the entries into a user space. The APIs used in this example are: 

e@ Create User Queue (QUSCRTUQ) 


e@ Execute Command (QCMDEXC) 


Requester Program (SUSQEXREQ) 


The following is a requester program using ILE C: 


[KKK KK KKK KK KK IR IA IA A I A A AA AA AA A I A / 


/* PROGRAM: SUSQEXREQ vA 
fe * / 
/* LANGUAGE: ILE C for OS/400 */ 
{* */ 
/* DESCRIPTION: THIS PROGRAM ENTERS COMMANDS TO BE PROCESSED ONTO */ 
/* A QUEUE CALLED 'TESTQ' IN LIBRARY 'QGPL'. THE USER WILL BE */ 
/* PROMPTED TO ENTER AS MANY COMMANDS (UNDER 51 CHARACTERS) AS * / 
/* IS DESIRED. WHEN THE USER WISHES TO END THE PROGRAMS, xf 
/* ALL THAT NEED BE DONE IS ENTER 'quit' AT THE PROMPT. * / 
as * / 
/* APIs USED: */ 
/* x 


[KK RK KK KK KK KK IR IA IA A I A AAA A AA A a I / 
#include <stdio.h> 

#include <string.h> 

#include <miqueue.h> 

#include <miptrnam.h> 


main () 

{ 

_ENQ_ Msg_Prefix_T e_msg_prefix; 
_SYSPTR queue; 

char INMsg[100]; 


[KKK KK KK KK KKK IA IA AA IA I A A AAA A IA A I I A / 


/* Resolve to the queue created by SUSQEXSRV. */ 


[KK RK KKK KKK KK KR IR IA IA IA I I A AAA AA A A I I / 


queue = rslvsp(_Usrq,"TESTQ", "OGPL", AUTH_ALL) ; 
e_msg_prefix.Msg_Len = 100; 


[ORK RK KK KKK KK KK IK IA IA IA I A AA AA AA AA A A I I A / 


/* Loop until the user enters 'quit' as the command. ai 


[OK KK KKK KK KKK IR IA IA AA I AA AA A A A a I I / 


while (1) { 
printf("\nEnter command to put on queue, or 'quit' \n "); 
scanf("%100s", INMsg) ; 
gets (INMsg) ; 
printf("\nCommand entered was ==> %.100s\n", INMsg) ; 


[ORK RK KK KK KK KK KK IK AA AA IA I I A AA AA AA A A a I I / 


/* Check to see if the user entered 'quit' as the command. */ 
/* If true then break out of the 'while' loop. my 


[KOK KK KK KK KK KK IA IA AA IA I I I A AA AAA AA IA A a  / 


if ((strncemp(INMsg, "quit",4) == 0) | | (strnemp (INMsg, "QUIT", 4) == 0)) 
{ break; } 


[ORK RK KK KKK KK KK IR IA IA IA I I AAA AA AA A IA A I I A / 


/* Add the user-entered command to the queue. */ 
[KK RK KK KKK KK KK IA AA IA A I A A AA AA A A I I A / 


eng (queue, &e_msg_prefix, INMsg) ; 
strcpy(INMsg," "); 
} /*while*/ 


[OK KK KK KK KK KK A IA IA IA I A A AAA AA AA A A a Ie / 


/* Add the command end to the queue which causes the oid 
/* server program (SUSQEXSRV) to end Kf. 


[KK RK KKK KK KK KKK IR IA IA IA I I A A AAA AA A A a I a / 


strcpy (INMsg, "END") ; 
enq (queue, &e_msg_prefix, INMsg) ; 
} /* SUSQEXREQ */ 


To create the requester program using ILE C, specify the following: 


CRTBNDC PGM(QGPL/SUSQEXREQ) SRCFILE(QGPL/QCSRC) 


Server Program (SUSQEXSRV) 


The following is the server program using ILE C: 


[KKK KKK KKK KK KK IA AA IA IA I A A A AA A A I I I I / 


/* PROGRAM: SUSQEXSRV ef 
/* vA 
/* LANGUAGE: ILE C for OS/400 */ 
ea */ 
/* DESCRIPTION: THIS PROGRAM EXTRACTS COMMANDS TO BE RUN FROM */ 
/* A QUEUE CALLED 'TESTQ' IN LIBRARY 'QGPL'. THE COMMANDS WILL */ 
/* BE EXTRACTED AND RUN IN FIFO ORDER. THE QUEUE WILL BE */ 
asi CREATED PRIOR TO USE AND SHOULD BE DELETED AFTER EACH USE Ff: 
/* OF THIS EXAMPLE PROGRAM. THIS PROGRAM END WHEN IT */ 
/* EXTRACTS THE COMMAND 'END' FROM THE QUEUE. */ 
/* THE FLOW IS AS FOLLOWS: */ 
ps (1) CREATE THE USER QUEUE */ 
/* (2) ENTER LOOP mf 
/* (3) WAIT FOREVER FOR A COMMAND ON THE QUEUE */ 
/* (4) IF COMMAND IS 'END' THEN EXIT LOOP aA 
br (5) ELSE RUN COMMAND, RESTART LOOP */ 
/* (6) END LOOP Fy 
/* FOR BEST RESULTS, THIS PROGRAM CAN BE CALLED BY THE USER, THEN*/ 
/* THE SUSQEXREQ SHOULD BE CALLED FROM ANOTHER SESSION. */ 
Vea */ 
/* APIs USED: QCMDEXC, QUSCRTUQ aA 


[ORK RK KK KK KK KKK IK AA IA A I AA AAA AA A A a I I / 


#include <stdio.h> 
#include <stdlib.h> 
#include <string.h> 
#include <micomput .h> 
#include <miqueue.h> 
#include <miptrnam.h> 
#include <quscrtuq.h> 
#include <qcmdexc.h> 


main () 


{ 
_DEQ Msg_Prefix_T d_msg_prefix; 


_SYSPTR queue; 

char OUTMsg[100]; 

int cmd_name_lingth; 
decimal (15,5) pack_name_lngth; 
char igc_param[] = "IGC"; 


[OK KK KK KKK KK KK IK IA IA IA I A AAA AA A A I a I / 


Ps Set up the parameters to be used in the call to 'QUSCRTUQ' */ 


[ORK RK KKK KK KK KK IK AA AA A I AAA AA A A I / 


char q_name[]= "TESTO QOGPL Me 
char ext_atr[]= "TESTER ws 
char q_type[]J= "F"; 


int key_lngth = 0; 
int max_msg_s 
int int_msgs 
int add_msgs = 50; 

char auth[] = "*ALL We 

char desc[] = "Description ..... Mes 


sll 
RR 
oo 
~~ Oo 
~ 


[OK KK KK KKK KKK IK KK AA AA A I AAA A A A A a I A / 


/* Call the 'QUSCRTUQ' program to create the user queue. */ 


[KK RK KK KKK KKK KK IA IA AA IA I A AAA A IA A I a I A / 


QUSCRTUQ(q_name, ext_atr,q_type, key_lngth,max_msg_s,int_msgs, 
add_msgs, auth, desc) ; 


[ORK RK KK KKK KK KKK IR IA AA A A AAA AA A A I  / 


/* Resolve to the queue created above. */ 
[ORK RK KK KK KK KK IK IA AA IA A I A AA AAA AA IA A I I / 


queue = rslvsp(_Usrq, "TESTQ", "OGPL", _ AUTH_ALL) ; 


[OK KK KK KKK KKK KK KR IA IA A I A A AAA AA A A a I A / 


/* Set the deq operation to wait for command indefinitely. */ 
KKK KK KKK KKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK K KKK KKK KKKKKKKKKKK KKK KK KKK 
/ / 


d_msg_prefix.Wait_Forever = 1; 


[ORK RK KK KKK KK KR IA AA AA A I A AA AAA AA A A I I A / 


/* Loop until the command 'END' is extracted from the queue */ 
[ORK RK KK KK KK KK KA IA IA IA I A AAA AA A A a Ie a / 


while (1) { 
deq(&d_msg_prefix, OUTMsg, queue) ; 


[KK RK KK KKK KK KR IR AA AA A I I A AAA AA AA AA A I I I / 


/* Check to see if the command extracted is 'END' mf 
/* If true then break out of the 'while' loop. */ 


[ORK RK KK KKK KK KK IR IA IA IA I A A AAA AA A A I I I / 


if (strncmp (OUTMsg, "END",3) == 0) 
{ break; } 


cmd_name_lngth = strlen(OUTMsg) ; 


[ORK RK KK KKK KK KK IK IA IA A I I A AA AA AA A A A a / 


/* Convert the integer in cmd_name_lngth to a packed decimal */ 
[ORK RK KK KK KKK KR IA AA IA A I I A A AAA AA A A I a I a / 


cpynv (NUM_DESCR(_T_PACKED,15,5), &pack_name_ingth, 
NUM_DESCR(_T_SIGNED,4,0), &cmd_name_lngth) ; 


[KK RK KK KKK KK KK IA AA AA A I A AAA IA A A a I I / 


/* Execute the command extracted from the queue *f 
[OK KK KK KK KK KK KK IA IR IA IA I I A A AAA A A I I A / 


QCMDEXC (OUTMsg, pack_name_lngth,igc_param) ; 


} /* while */ 
} /* SUSQEXSRV */ 


To create the server program using ILE C, specify the following: 


CRTBNDC PGM(QGPL/SUSQEXSRV) SRCFILE(QGPL/QCSRC) 


Defining Queries 


This topic includes several examples that use the Query (QQQQRY) API. The examples define the following query functions: 


e A simple query to perform ordering 
e A join query 


e A join query with selection grouping and ordering 


The following QQAPI header (or include) file and the QQFUNCS query code are used by all the examples. The example programs 
follow the QQAPI header and QQFUNCS code. 


QQAPI Header 


[OK KK KK KK KK KR IR AA IA A I IAA AA AAA AA A A I I I / 


#ifndef _QQAPIH 
#define _QQAPIH 


[OK KK KKK KK KK KI IA A A A I A A AA AA IA AA A A I A I I He / 
[KK RK KK KK KK KKK AA IA IA A A A AIA AA AA A I A I A I I I 


/* *f 
/* FUNCTION: Defines constants and structures for use vA 
/* with the QQQQRY API examples. #f: 
Ve */ 
/* LANGUAGE: ILE C for OS/400 */ 
/* ad 
/* APIs USED: None */ 
Va ia’ 


[BKK RK KK KK KKK IK IA IA A A A A A AA IA A A A I A I 
[KK RK KK KKK KK KKK A AA IA A A AA AA IA IA IA I A A I I He / 


/* The following define will enable some debug procedures and code */ 
/* #define QQDEBUG */ 


/* Query Open options */ 
#define QO_INPUT 1 


#define QO_OUTPUT 2 
#define QO_UPDATE 4 
#define QO_DELETE 8 


/* simple defines */ 
#define ON 1 
#define OFF 0 


/* user defined limits - change as needed */ 
#define MAX _ORDERBY 20 

/* max number of order by fields (8000 max) */ 
#define MAX_JOINTESTS 20 

/* max number of join tests (999 max) */ 


#define MAX _GROUPBY 20 

/* max number of order by fields (120 max) */ 
/* storage sizes - increase if needed */ 
#define QDT_SIZE 6000 


#define FORMAT_SIZE 5000 
#define SELECT_SIZE 5000 
#define AP_SIZE 65535 /* Initialize access plan size to 64K */ 


/* Required definitions - do NOT change, hard limits */ 


#define MAX_FILES 32 /* Maximum number of files in a query */ 
#define REQ REL "OT" /* Required value for release field */ 
#define REQ_VER "00" /* Required value for version field */ 
#define QFLD_SIZE 30 /* QQ API field size - see qqqqry.h */ 


/* define error code structure */ 
typedef struct 
{ 
int bytes_provided; 
int bytes_available; 
char msgid[(7]); 
char reserved; 
char data[(512]); 
} error_code; 


/* define attribute record for QUSCUSAT API */ 
typedef _Packed struct 
{ 
int numAttrs; 
int key; 
int length; 
_Packed union { 
long spaceSize; /* key 1 */ 
char initialValue; /* key = 2 */ 
char autoExtend; /* key = 3 */ 
} data; 
} QUSCUSAT_T; 


/* define access plan structure */ 
typedef _Packed struct 
{ 
_SPCPTR storagePtr; 
long size; 
char reserved[ (28]); 
} ACCPLN_T; 


/* Function prototypes: */ 
void dumpPtr(char *, char *, int ); 
char *strcenv400(char *, int ); 
int strcpy400(char *, char *, int ); 
void initUFCB(QDBUFCB_T *, int , Qdb_Qddfmt_t *); 
void initQDT(QDBOH_T *, char , int , int , 
char , int ); 


void initFile(QDBOFHDR_T *, char , char ); 
void initFormat (Qdb_OQddfmt_t *, char *); 
void initSelection(QDBQS_T *); 
void initOrderBy (QDBOKH_T *); 
void initGroupBy (QDBOQGH_T *); 
void initJoin(QDBQJHDR_T *); 
int addFile(QDBOFHDR_T *, QDBOQN_T *, 
char *, char *, char *, char *); 
int getRecordFmt (Qdb_Qddfmt_t *, long, 
char *, char *, char *); 
long copyField(Qdb_Qddfmt_t *, char *, int , 
Qdb_Qddfmt_t *); 
void setFieldUsage (Qdb_Qddfmt_t *, char *, char ); 
int addSelectField(QDBQS_T *, char *, int ); 
int addSelectLiteral (QDBOS_T *, void *, int ); 
int addSelectOperator(QDBQOS_T *, char *); 
int addOrderBy (QDBOKH_T *, QDBOKF_T *, 
char *, int ); 
int addGroupBy (QDBOQGH_T *, QDBOQGF_T *, 
char *, int ); 
int addJoinTest (QDBQJHDR_T *, QDBQUFLD_T *, char *, 
int , char *, int , char *); 
void addQDTsection(QDBQH_T *, char *, int , int *); 
long createAccessPlanSpace (ACCPLN_T *, char *, long ); 
int saveQDT(QDBOQH_ T *, ACCPLN_T *); 
int saveAccessPlan(ACCPLN_T *); 
int loadQDT(QDBOQH_T *, ACCPLN_T *); 
long loadAccessPlan(ACCPLN_T *, char *); 


#fendif 


[KK RK KK KKK KK KK IK AA KA IA I I AAA AA IA A a a / 


QQFUNCS Query Code 


[ORK RK KK KK KK KKK IR IA IA IA I I A AA AAA AA IA A I a I a / 


#include <stdio.h> 
#include <string.h> 
#include <qdbrtvfd.h> 
#include <qqqqry.h> 
#include <quscrtus.h> 
#include <qusptrus.h> 
#include <quscusat.h> 
#include <qusrusat.h> 
#include "qqapi.h" 
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/* */ 
/* FUNCTION: This module contains all of the functions ard 
f* used by the examples to build the API information. */ 
/* */ 
/* LANGUAGE: ILE C for OS/400 */ 
ps ay! 
/* APIs USED: QDBRTVFD, QUSCRTUS, QUSCUSAT, QUSPTRUS, QUSRUSAT */ 
i */ 


[ORK RK KK KKK KK KKK A IA A A A RA AA A A A A A I I 
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#ifdef QQDEBUG 
/* dumpPtr(comment string, pointer, length) 
— prints a comment then dumps data in hexadecimal starting at the 
given pointer location for the specified length */ 
void dumpPtr(char *text, char *ptr, int len) 


{ 


int: 4; 


printf("%s\n", text); 
for (i=0; i < len; i++, ptr++t) 
{ 
printf("S02xX ", (int) *ptr); 
if ((it1) % 16 == 0) 
printf ("\n"); 
} 
printf ("\n"); 
} 
f#endif 


/* strcenv400(source string, string length) 
— convert an OS/400 string to a zero terminated string */ 
char *strcenv400(char *str, int len) 


{ 
static char buffer[256]; 


strncpy (buffer, str, len); 
buffer[len] = (char) 0; 
return (buffer) ; 


/* strcepy400 (destination string, source string, source length) 

—- copy a zero terminated string to an OS/400 string, pad with blanks 
if necessary */ 

int strcpy400(char *dest, char *src, int len) 


{ 


int i; 

if ((i = strlen(src)) > len) 
len = i; 

if (len) 


memcpy (dest, src, strlen(src)); 
if (i < len) 

memset ((dest+i), ' ', len-i); 
return(len); 


/* initUFCB(ufcb, open options, record format) 

—- initialize the UFCB structure */ 

void initUFCB(QDBUFCB_T *ufcbPtr, int openFlags, 
Qdb_OQddfmt_t *formatPtr) 


{ 
_Packed struct qufcb *ufchb; 


/* verify parameters */ 
if (ufcbPtr == NULL | | openFlags == 0) 
{ 
printf ("Invalid UFCB settings\n"); 
return, 
} 
/* Clear the entire UFCB */ 
memset ((void *) ufcbPtr, (char) 0, sizeof (QDBUFCB_T) ); 
/* Now start initializing values */ 
ufcb = &ufcbhPtr-&gt;qufcbh; 
strcepy400((char *) ufcb-—>relver.release, REQ REL, 
sizeof (ufcb->relver.release) ); 
strcpy400((char *) ufcb->relver.version, REQ_VER, 
sizeof (ufcb->relver.version) ); 
/* Blocked Records (BLKRCD) should be on if CPYFRMQRYF is used */ 
ufcb->markcnt.flg2brcd = ON; 
ufcb-—>parameter.maximum = MAXFORMATS; 


/* Set the open option */ 
if (openFlags&QO_INPUT) 


ufcb->open.flagui = ON; 
if (openFlags&QO_OUTPUT) 
ufcbh—>open.flaguo ON; 


if (openFlags&QO_UPDATE) 
ufcbh—>open.flaguu = ON; 
TK 


if (openFlags&QO_DELETE) 
ufcbh—>open.flagud ON; 

/* set up options to match _Ropen options */ 
ufcb—>parameter.keyfdbk = KEYFDBK; 
ufcb->parameter.keyonoff = ON; /* Key feedback ON */ 
ufcb—>parameter.filedep = FILEDEP; 
ufcb->parameter.fldonoff = ON; /* File dependent I/O ON */ 
/* turn the rest of the parameters off */ 
ufcb-—>parameter.seqonly = NOTSEQUPROC; 
ufcb—>parameter.primrilnl = NOTRECORDLTH; 
ufcb—>parameter.commitc = NOTCOMITCTL; 
/* if the format is supplied, 

define it in the UFCB and do level checking */ 
if (formatPtr != NULL) 
{ 


ufcbh—>parameter.lvlchk = LEVELCK; 
ufcb->parameter.lvlonoff = ON; /* Level check ON */ 
ufcb->parameter.curnum = 1; /* only one format */ 
/* set the format name and format level identifier */ 
ufcbh—>parameter.recfmts = FORMATSEQ; 
memcpy (ufcb->parameter.formats[0].name, formatPtr->Qddfname, 
sizeof (ufcb-—>parameter.formats[0].name)); 
memcpy (ufcb->parameter.formats[0].number, formatPtr->Qddfseq, 
sizeof (ufcb-—>parameter. formats [0].number) ); 
} 
else /* no format and level checking */ 
{ 
ufcbh—>parameter.lvlchk = NOTLEVELCK; 
ufcbh—>parameter.recfmts = NOTFORMATSEQ; 
} 
ufcb->ufcbend = ENDLIST; 


/* initQDT(qdt, options...) 
— initialize the QDT header */ 
void initQDT(QDBOH_T *qdtHdr, char alwCpyDta, 
int optAllAp, int statusMsgs, 
char optimize, int forRows) 
{ 
if (qdtHdr == NULL) 
{ 
printf ("Invalid QDT settings\n"); 
return; /* invalid pointer */ 
} 
/* Clear the entire QDT */ 
memset ((void *) qdtHdr, (char) 0, sizeof (QDBQH_T)); 
/* set the initial QDT space used size */ 
qdtHdr->qdbspcsize = sizeof (QDBOH_T); 


/* QDT options... */ 

/* ordering not specified */ 

qdtHdr->qdbqkeyo = -1; 

/* set optimize parameter (ALLIO, FIRSTIO, MINWAIT) */ 

if (optimize == QDBOFINA || optimize == QDBOFINF | | 
optimize == QDBOFINM || optimize == QDBOFINC) 

qdtHdr->qdbqfin = optimize; /* OPTIMIZE() parameter */ 
else 


qdtHdr->qdbqfin = QDBOFINA; /* default to OPTIMIZE(*ALLIO) */ 
/* set allow copy data parameter (YES, NO, OPTIMIZE) */ 
if (alwCpyDta == QDBOTEMN || alwCpyDta == QDBOTEMO | | 


alwCpyDta == QDBQTEMA) 

qdtHdr->qdbqtem = alwCpyDta; /* ALWCPYDTA() parameter */ 
else 

qdtHdr->qdbgqtem = QDBOTEMA; /* default to ALWCPYDTA(*YES) */ 
/* status messages (YES, NO) */ 
qdtHdr->qdbgattr.qdbqnst = statusMsgs ? ON : OFF; 
/* optimize all access path parameter (YES, NO) */ 
qdtHdr->qdbqdt_7.qdbqopta = optAllAp ? ON : OFF; 
/* optimizer for n rows parameter */ 
qdtHdr->qdbq_optmrows = forRows > 0 ? forRows : 0; 


/* initFile(file section, join type, join order option) 
— initialize the file header section */ 
void initFile(QDBOFHDR_T *fileHdr, char joinType, char joinOrder) 
{ 
if (fileHdr == NULL) 
{ 
printf ("Invalid File Header settings\n"); 
return; /* invalid pointer */ 
} 
/* Clear the header */ 
memset ((void *) fileHdr, (char) 0, sizeof (QDBOQFHDR_T)); 


/* File Spec options... */ 
/* inner, partial outer or exception join type */ 
if (joinType == QDBOINNJ | | joinType == QDBOQOUTJI | | 
joinType == QDBOEXCJ) 

fileHdr-—>qdbqmfop = joinType; 
else 

fileHdr-—>qdbqmfop = QDBOINNUJ; 
/* join order - any order or join as specified */ 
fileHdr->qdbqmfor = joinOrder == QDBOMFON ? QDBOMFON : QDBOMFOA; 


/* initFormat (format section, format name) 

— initialize the format header section */ 

void initFormat (Qdb_Qddfmt_t *formatHdr, char *name) 

{ 
if (formatHdr == NULL) 
{ 

printf ("Invalid Format Header settings\n") ; 
return; /* invalid pointer */ 

} 
/* Clear the header */ 
memset ((void *) formatHdr, (char) 0, sizeof (Qdb_Qddfmt_t) ); 
/* Format Spec options... */ 
strcpy400 (formatHdr->Qddfname, name, sizeof (formatHdr—->Qddfname) ) ; 
formatHdr->Qddfreid = 65535; 
formatHdr—->Qddfsrcd = 65535; 
formatHdr->Qddflgs.Qddfrsid = 1; 
memset (formatHdr->Qddfseq, ' ', sizeof (formatHdr-—>Qddfseq) ); 
memset (formatHdr->Qddftext, ' ', sizeof (formatHdr->Qddftext) ); 
/* Format size (so far) */ 
formatHdr->Qddbyava = sizeof (Qdb_Qddfmt_t); 
formatHdr->Qddbyrtn = formatHdr->Qddbyava; 


/* initSelection(selection section) 
- initialize the selection header section */ 
void initSelection(QDBQS_T *selectHdr) 
{ 
if (selectHdr == NULL) 
{ 


printf ("Invalid selection settings\n"); 


return; /* invalid pointer */ 
} 
/* Clear the header */ 
memset ((void *) selectHdr, (char) 0, sizeof (QDBQS_T)); 
/* set initial selection spec size (minus dummy selection spec) */ 
selectHdr-—>qdbqsl = sizeof (QDBOQS_T) - sizeof (selectHdr-—>qdbqspec) ; 


/* initOrderBy (orderby section) 
— initialize order by header section */ 
void initOrderBy (QDBOKH_T *orderByHdr) 
{ 
if (orderByHdr == NULL) 
{ 
printf ("Invalid Order By settings\n"); 
return; /* invalid pointer */ 
} 
/* Clear the header */ 
memset ((void *) orderByHdr, (char) 0, sizeof (QDBOQKH_T)); 


/* initGroupBy (groupby section) 
—- initialize group by header section */ 
void initGroupBy (QDBOGH_T *groupByHdr) 
{ 
if (groupByHdr == NULL) 
{ 
printf ("Invalid Group By settings\n"); 
return; /* invalid pointer */ 
} 
/* Clear the header */ 
memset ((void *) groupByHdr, (char) 0, sizeof (QDBOQGH_T)); 


/* initJoin(join section) 
- initialize join header section */ 
void initJoin(QDBQJHDR_T *joinHdr) 
{ 
if (joinHdr == NULL) 
{ 
printf ("Invalid Join settings\n"); 
return; /* invalid pointer */ 
} 
/* Clear the header */ 
memset ((void *) joinHdr, (char) 0, sizeof (QDBOKH_T)); 
/* set initial join spec size */ 
joinHdr—->qdbqjln = sizeof (QDBQJUHDR_T) ; 


/* addFile (file section, file spec section, file name, file library, 
file member, file format) 
- add file information to the file section */ 
int addFile(QDBOFHDR_T *fileHdr, QDBON_T *fileSpec, 
char *filename, char *library, char *member, char *format) 
{ 
int i; 
QDBOFLMF_T *fileSpecPtr; 


if (fileHdr == NULL || fileSpec == NULL || filename == NULL) 
return(0); /* invalid data */ 

if (fileHdr->qdbqfilnum == MAX_FILES) 
return(0); /* no more files allowed */ 

/* increment the count of file specs */ 


i = fileHdr->qdbqfi 
/* initialize the f 
memset ((void *) 
fileSpecPtr = 
/* fill in the data 


strcpy400 (fileSpecPtr-—>qdbqfile, 


lnumt++; 
ile spec area */ 


sizeof (fileSpecPtr-—>qdbqfile) ); 


leSpecPtr-—>qdbqlib, 
eSpecPtr-—>qdbqlib) ); 


leSpecPtr-—>qdbaqmbr, 
eSpecPtr->qdbqmbr) ) ; 


leSpecPtr-—>qdbaqmbr, 
eSpecPtr->qdbqmbr) ); 


leSpecPtr-—>qdbqfmt, 


sizeof (fileSpecPtr—>qdbqfmt) ); 


if (library == NULL) 
strcpy400 (fi 
sizeof (fil 
else 
strcpy400 (fi 
sizeof (fil 
if (member == NULL) 
strcpy400 (fi 
sizeof (fil 
else 
strcpy400 (fi 
sizeof (fil 
if (format == NULL) 
strcpy400 (fi 
else 


strcpy400 (fileSpecPtr-—>qdbqfmt, 


sizeof (fileSpecPtr—>qdbqfmt) ); 


/* return the amount of storage used in the file specs 


&éfileSpec[i], (char) 0, sizeof (QDBOQN_T)); 
(QDBOFLMF_T *) &fileSpec[i] .qdbgqflmf; 
ye 
filename, 


leSpecPtr-—>qdbqlib, QDBOLIBL, 


eSpecPtr-—>qdbqlib) ); 


library, 


QDBOFRST, 


member, 


QDBQONLY, 


format, 


*/ 


return (fileHdr-—>qdbqfilnum*sizeof (QDBOQN_T)); 


/* getRecordFmt (format, 
file name, 
- get a record format 


file library, 


format storage size(max), 


file format) 


(using QDBRIVFD) */ 


int getRecordFmt (Qdb_Oddfmt_t *formatPtr, 
char *filename, 


{ 


char *libname, 


error_code errcod; 


long spaceSize, 
char *formatname) 


char override = '1'; /* process overrides */ 

char fileLibname [20]; 

char outFilLib[20]; 

char format[10]; 

if (formatPtr == NULL || filename == NULL) 
return(0); /* missing data */ 

errcod.bytes_provided = 512; 

errcod.msgid[0] = (char) 0; 


/* set up temporary variables... 
filename, 


strcpy400 (fileLibname, 
if (libname NULL) 


strcpy400 (éfileLibname[10], 


else 


strcpy400 (&fileLibname[10], 


if (formatname ULL) 
strcpy400 (format, 
else 


strcpy400 (format, 


filename, 


formatname, 


sabe 

10); 
QDBQLIBL, 10); 
libname, 10); 
10); 


10); 


/* call the RTVFD API to get the record format */ 


QDBRTVFD((char *) formatPtr, spaceSize, outFilLib, 
"FILDO200", 
fileLibname, format, &override, 
WALCE ", “*EXT ", &errcod); 


if 
{ 


(errcod.msgid[0]) 


printf ("API QDBRTVFD failed\n") ; 


printf ("msgid = %7s\n", 
sizeof (errcod.msgid) )); 


strcnv400 (errcod.msgid, 


if (formatPtr->Qddbyrtn != formatPtr-—>Qddbyava) 
return(0); /* missing data */ 

/* return total storage used in format */ 

return (formatPtr->Qddbyrtn) ; 


/* copyField(format, field name, file number, existing format) 


- copy a field from an existing format */ 


long copyField(Qdb_Qddfmt_t *formatPtr, char *fieldName, int fieldFile, 


{ 


Qdb_OQddfmt_t *oldFormatPtr) 


int a; 

long fieldSize; 

char padField[30]; 

Qdb_Qddffld_t *fieldPtr, *oldFieldPtr; 


if (formatPtr == NULL || fieldName == NULL || oldFormatPtr == NULL) 
return(0); /* missing data */ 

strcpy400(padField, fieldName, 30); 

/* set up field pointers */ 


fieldPtr = (Qdb_Qddffld_t *) ((char *) formatPtr + 
formatPtr->Qddbyava) ; 
oldFieldPtr = (Qdb_Qddffld_t *) (oldFormatPtr + 1); 


/* loop through all the fields, looking for a match */ 
for (i=0; i < oldFormatPtr-—>Qddffldnum; i++, 


oldFieldPtr = (Qdb_Qddffld_t *) ((char *) oldFieldPtr + 
oldFieldPtr->Qddfdefl) ) 
/* if a match was found... */ 


if (memcmp (oldFieldPtr->Qddfflde, padField, 30) == 0) 
{ 
/* copy the field over */ 
fieldSize = oldFieldPtr-—>Qddfdefl; 
memcpy (fieldPtr, oldFieldPtr, fieldSize); 
/* set the file number it was defined in */ 
fieldPtr->Qddfjref = fieldFile; 
/* increment the format header information */ 
formatPtr-—>Qddffldnum++; 


formatPtr->Qddfrlen += fieldPtr->Qddffldb; 
formatPtr->Qddbyava += fieldSize; 
formatPtr->Qddbyrtn = formatPtr-—>Qddbyava; 
break; 


} 
/* return total storage used in format */ 
return (formatPtr—->Qddbyrtn) ; 


/* setFieldUsage(format, field name, usage) 


—- set the field usage in a format */ 


void setFieldUsage (Qdb_Qddfmt_t *formatPtr, char *fieldName, char usage) 


{ 


int i; 
char padField[30]; 
Qdb_Qddffld_t *fieldPtr; 


if (formatPtr == NULL) 
return; /* missing data */ 
if (fieldName != NULL) 


strcpy400 (padField, fieldName, 30); 
/* set up field pointers */ 
fieldPtr = (Qdb_Qddffld_t *) (formatPtr + 1); 
/* loop through all the fields, looking for a match */ 
for (i=0; i < formatPtr->Qddffldnum; i++, 
fieldPtr = (Qdb_Qddffld_t *) ((char *) fieldPtr + 
fieldPtr->Qddfdefl) ) 
/* if all fields to be set or a match was found... */ 


if (fieldName == NULL | | 
memcmp (fieldPtr->Qddfflde, padField, 30) == 0) 
fieldPtr->Qddffiob = usage; 


/* addSelectField(section section, field name, file number for field) 


- add a selection for a file field to the selection section */ 


int addSelectField(QDBQS_T *selectHdr, char *fieldName, int fieldFile) 


{ 


QDBOSIT_T *selectItemPtr; 
QDBOSOPF_T *selectFldPtr; 
int itemSize; 


if (selectHdr == NULL || fieldName == NULL) 
return(0); /* invalid data */ 
/* set up all the section for adding a field */ 


selectItemPtr = (QDBQOSIT_T *) ((char *) selectHdr + 
selectHdr-—>qdbqs1); 

itemSize = sizeof(QDBOSIT_T) - sizeof(selectItemPtr-—>qdbqsitm) ; 

memset ((void *) selectItemPtr, (char) 0, itemSize); 

selectFldPtr = (QDBQSOPF_T *) ((char *) selectItemPtr + itemSize); 


memset ((void *) selectFldPtr, (char) 0, sizeof (QDBOSOPF_T))j; 
/* set up the selection item information for a field */ 
selectItemPtr-—>qdbgqslen = itemSize + sizeof (QDBQSOPF_T) ; 
/* length */ 
selectItemPtr-—>qdbqsitt = QDBQOPF; /* type is field */ 
/* now set up the field */ 
strcpy400(selectFldPtr->qdbqsofn, fieldName, 

sizeof (selectFldPtr-—>qdbqsofn) ); 
selectFldPtr-—>qdbqsofj = fieldFile; 
/* update the header statistics */ 
selectHdr->qdbqsnumt++; /* increment number of select specs */ 
selectHdr->qdbqsl += selectItemPtr->qdbqslen; /* total length */ 
/* return the total storage now in the selection section */ 
return (selectHdr->qdbqs1) ; 


/* addSelectLiteral(selection section, literal, size of literal data) 


- add a selection for a literal to the selection section */ 


int addSelectLiteral (QDBQS_T *selectHdr, void *literal, int sizeLit) 


{ 


QDBOSIT_T *selectItemPtr; 
QDBQOSOCH_T *selectLitPtr; 
void *selectDataPtr; 

int itemSize; 


if (selectHdr == NULL || literal == NULL || sizeLit < 1) 
return(0); /* invalid data */ 
/* set up all the sections for adding a literal */ 


selectItemPtr = (QDBOSIT_T *) 

((char *) selectHdr + selectHdr->qdbqs1) ; 
itemSize = sizeof(QDBOSIT_T) - sizeof(selectItemPtr-—>qdbqsitm) ; 
memset ((void *) selectItemPtr, (char) 0, itemSize); 
selectLitPtr = (QDBQSOCH_T *) ((char *) selectItemPtr + itemSize); 
memset ((void *) selectLitPtr, (char) 0, sizeof (QDBQSOCH_T)); 
selectDataPtr = (void *) (selectLitPtr + 1); 
/* set up the selection item information for a literal */ 
selectItemPtr—>qdbqslen = itemSize + sizeof (QDBOQSOCH_T) + sizeLit; 


selectItemPtr-—>qdbqsitt = QDBQOPC; /* literal type */ 
/* now set up the literal */ 
selectLitPtr->qdbqsocl = sizeLit; /* literal size */ 
selectLitPtr->qdbqsoft '\xFF'; 

/* use job format for date/time fields */ 
memcpy (selectDataPtr, literal, sizeLit); 

/* save the literal value */ 


/* update the header statistics */ 
selectHdr->qdbqsnum++; 
selectHdr->qdbqsl += selectItemPtr—>qdbqslen; 


/* increment number of select specs */ 


/* total length */ 


/* return the total storage now in the selection section */ 


return (selectHdr->qdbqs1) ; 


/* addSelectOperator (selection section, 


operator type) 


- add a selection for an operator to the selection section */ 


int addSelectOperator(QDBQOS_T *selectHdr, 
{ 

QDBOSIT_T *selectItemPtr; 

QDBQOSOPR_T *selectOprPtr; 

QDBOQSOP2_T *selectWldPtr; 

int itemSize; 

int oprSize; 


if (selectHdr == NULL || operator == NULL) 
return(0); /* invalid data */ 


char *operator) 


/* set up all the sections for adding an operator */ 


selectItemPtr = (QDBOSIT_T *) 

((char *) selectHdr + selectHdr-—>qdbqs1); 
itemSize = sizeof (QDBOSIT_T) 
memset ((void *) selectItemPtr, (char) 0, 
selectOprPtr = (QDBOQSOPR_T *) ((char *) 


oprSize = sizeof (QDBQSOPR_T) 


memset ((void *) selectOprPtr, (char) 0, 


— sizeof (selectItemPtr—>qdbqsitm) ; 
itemSize) ; 

selectItemPtr + itemSize); 

+ sizeof (QDBOSOP2_T); 

oprSize); 


/* set up the selection item information for an operator */ 


selectItemPtr—>qdbqslen = itemSize + oprSize; 

selectItemPtr—>qdbgqsitt = QDBQOPTR; 

/* now set up the operator */ 

memcpy (selectOprPtr->qdbqsop, operator, 
sizeof (selectOprPtr-—>qdbqsop) ) ; 

/* wildcard operator set up */ 


if (memcmp (operator, QDBQWILD, 2) == 0) 
{ 
selectOprPtr->qdbqswel = '_'; 
selectOprPtr->qdbqswe2 = '*'; 


selectWldPtr = (QDBQSOP2_T *) 
memcpy (selectWldPtr->qdbqsdb1,"\42_", 2); 
memcpy (selectWldPtr->qdbqsdb2,"\42*", 2); 
} 
/* update the header statistics */ 
selectHdr-—>qdbqsnumt++; 
selectHdr->qdbqsl += selectItemPtr-—>qdbqslen; 


/* length */ 


/* operator type */ 


(selectOprPtr + 1); 


/* increment number of select specs */ 


/* total length */ 


/* return the total storage now in the selection section */ 


return (selectHdr-—>qdbqs1) ; 


/* addOrderBy(orderby section, 
descend sort option 
—- add an order by to the order by section */ 
int addOrderBy (QDBOKH_T *orderByHdr, 
char *keyfield, int descend) 
{ 
int i; 
QDBOKF_T *orderByFldPtr; 


orderby specs section, 


key field name, 


QDBOKF_T *orderByFld, 


if (orderByHdr == NULL || orderByFld == NULL || keyfield == NULL) 


return (0); 
if (orderByHdr->qdbqknum == MAX_ORDERBY) 
return (0); 
/* increment the order by spec counter */ 
i = orderByHdr->qdbqknum++; 
/* add the new orderby data */ 


orderByFldPtr = &orderByFld[i]; 
memset ((void *) orderByFldPtr, (char) 0, sizeof (QDBOKF_T) ); 
strcpy400 (orderByFldPtr—->qdbqkfld, keyfield, 

sizeof (orderByF1ldPtr-—>qdbqkfld) ); 
orderByFldPtr—>qdbqksq.qdbqksad = (descend) ? ON : OFF; 
/* return the space used by the order by specs */ 
return (orderByHdr->qdbqknum*sizeof (QDBOKF_T) ); 


/* addGroupBy(groupby section, groupby field spec section, 
groupby field name, file number of groupby field) 
—- add a group by to the group by section */ 
int addGroupBy (QDBOQGH_T *groupByHdr, QDBOGF_T *groupByFld, 
char *groupfield, int fromFile) 
{ 
ints ay 
QDBOGF_T *groupByFldPtr; 


if (groupByHdr == NULL | | groupByFld == NULL | | groupfield == NULL) 
return (0); 
if (groupByHdr->qdbqgfnum == MAX_GROUPBY) 


return (0); 
/* increment the group by spec counter */ 
i = groupByHdr->qdbqgfnumt++; 
/* add the new groupby data */ 
groupByFldPtr = (QDBOGF_T *) &groupByFld[i]; 
memset ((void *) groupByFldPtr, (char) 0, sizeof (QDBOQGF_T) ); 
strcpy400 (groupByFldPtr-—>qdbqgfld, groupfield, 
sizeof (groupByFldPtr-—>qdbaqgfld) ); 
groupByFldPtr->qdbqgflj = fromFile; 
/* return the space used by the group by specs */ 
return (groupByHdr—>qdbqgfnum* sizeof (QDBOGF_T)); 


/* addJoinTest (join section, join test section, join from field name, 
join from file number, join to field name, join to file number, 
join operator) 

- add a join test to the join section */ 
int addJoinTest (QDBOQJHDR_T *joinHdr, 
QDBQJFLD_T *joinSpec, char *fromFld, 
int fromFile, char *toFld, int toFile, char *joinOp) 


int i; 
QDBOQJFLD_T *joinSpecPtr; 


if (joinHdr == NULL | | joinSpec == NULL) 
return (0); 
if (joinHdr->qdbqjknum == MAX_JOINTESTS) 


return (0); 
/* increment the join test counter */ 
i = joinHdr->qdbqjknumt+; 
memset ((void *) &joinSpec[i], (char) 0, sizeof (QDBOQJFLD_T) ); 
/* add the new join data */ 
joinSpecPtr = &joinSpec[i]; 
strcpy400 (joinSpecPtr-—>qdbqjfnm, fromFld, 

sizeof (joinSpecPtr-—>qdbqjfnm) ) ; 
joinSpecPtr->qdbqjfnum = fromFile; /* 1, 2, 3, etc */ 
strcpy400 (joinSpecPtr-—>qdbqjtnm, toFld, 

sizeof (joinSpecPtr-—>qdbqjtnm) ); 
joinSpecPtr->qdbqjtnum = toFile; /* 1, 2, 3, etc */ 
/* Join operator - see #defines in QQ API include */ 
strcpy400 (joinSpecPtr->qdbqjop, joinOp, 

sizeof (joinSpecPtr-—>qdbqjop) ); 
/* set size of entire join spec */ 
joinHdr—->qdbqjln += sizeof (QDBOQUFLD_T) ; 


/* return the space used by the join tests */ 
return (joinHdr->qdbqjknum*sizeof (QDBQUFLD_T) ); 


/* addQDTsection(qdt, new section, size of new section, qdt offset) 
— place a new section into the QDT */ 
void addQDTsection(QDBQH_T *qdtHdr, char *newSection, 
int newSize, int *offset) 
{ 


char *sectionPtr; 


/* position to the current end of the QDT */ 
sectionPtr = (char *) qdtHdr + qdtHdr-—>qdbspcsize; 
/* append in the new section data */ 
memcpy (sectionPtr, newSection, newSize); 
/* if an offset is to be stored, remember it now */ 
if (offset != NULL) 

*offset = qdtHdr->qdbspcsize; 
/* update the QDT size */ 
qdtHdr->qdbspcsize += newSize; 


/* createAccessPlanSpace (access plan, user space name, size) 
— creates a *USRSPC object for storing the access plan */ 
long createAccessPlanSpace (ACCPLN_T *accessPlan, char *name, 

long spaceSize) 

{ 
QUSCUSAT_T chgAttr; 
_SPCPTR usrSpcPtr; 
char library[10]; 
char value = (char) 0; 
char text[50]; 
error_code errcode; 


errcode.bytes_provided = 512; 


strcpy400(text,"Access Plan for QQ API example",50); 
/* Create the User Space */ 
QUSCRTUS (name, 
"ACCESSPLAN", 
spaceSize, 
&évalue, 
"XALL mM 
text, 
"*kYES ms, 
&errcode, 
"*XUSER " ) ; 
if (errcode.msgid[0]) 


printf ("Create User Space API failed!\n"); 

printf ("msgid = %7s\n", strcnv400(errcode.msgid, 
sizeof (errcode.msgid) )); 

return (-1); 


} 


/* Change the User Space to allow Auto-Extend */ 
strcpy400 (library, &name[10],10); 
chgAttr.numAttrs = 1; 

chgAttr.key = 3; /* Auto extend */ 
chgAttr.length = sizeof(char); 


chgAttr.data.autoExtend = '1'; 
QUSCUSAT (library, 

name, 

échgAttr, 


&errcode) ; 


if (errcode.msgid[0]) 


printf ("Change User Space Attributes FAILED! \n"); 

printf ("msgid = %7s\n", strcnv400(errcode.msgid, 
sizeof (errcode.msgid) )); 

return (-1); 


} 


/* Retrieve Space Pointer to the User Space */ 
QUSPTRUS (name, 
&usrSpcPtr, 
&errcode) ; 
if (errcode.msgid[0]) 
{ 
printf ("Retrieve Space Pointer to User Space FAILED!\n"); 
printf ("msgid = %7s\n", strcnv400(errcode.msgid, 
sizeof (errcode.msgid) )); 
return (-1); 
} 
/* Now move to the access plan itself (on 16 byte boundary) */ 
accessPlan->storagePtr = (_SPCPTR) ((char*) usrSpcPtr + 16); 


return (0); 


/* saveAccessPlan(access plan) 
—- update the size in the access plan (QQQQRY actually wrote the data) */ 
int saveAccessPlan(ACCPLN_T *accessPlan) 


{ 
_SPCPTR usrSpcPtr; 


/* Position to the start of the user space */ 
usrSpcPtr = (_SPCPTR) ((char*) accessPlan->storagePtr —- 16); 
/* Write the access plan size out at the start */ 
memcpy (usrSpcPtr, (void *) &accessPlan->size, 
sizeof (accessPlan->size) ); 
#ifdef QQDEBUG 
printf("AP size = %ld\n", accessPlan->size) ; 
#endif 
return (0); 


} 


/* saveQDT(qdt, access plan) 

—- append the QDT to the end of the access plan */ 
int saveQDT(QDBOQH_T *qdtPtr, ACCPLN_T *accessPlan) 
{ 

_SPCPTR usrSpcPtr; 


/* Position to the just after the access plan */ 
usrSpcPtr = (_SPCPTR) ((char*) accessPlan->storagePtr + 
accessPlan->size); 
/* Write the QDT size out */ 
memcpy (usrSpcPtr, &qdtPtr->qdbspcsize, sizeof (qdtPtr-—>qdbspcsize) ); 
#ifdef QQDEBUG 
printf("qdt size = %ld\n", qdtPtr->qdbspcsize) ; 


#endif 
/* Move up the user space pointer */ 
usrSpcPtr = (_SPCPTR) ((char *) usrSpcPtr + 16); 


/* Write the QDT itself out */ 
memcpy(usrSpcPtr, qdtPtr, gqdtPtr-—>qdbspcsize) ; 
return(0); 


/* loadQDT(qdt, access plan) 


—- load the QDT from the end of the access plan */ 
int loadQDT(QDBOQH_T *qdtPtr, ACCPLN_T *accessPlan) 
{ 

_SPCPTR usrSpcPtr; 


/* Position to the just after the access plan */ 

usrSpcPtr = (_SPCPTR) ((char*) accessPlan->storagePtr + 
accessPlan->size)j; 

/* Write the QDT size out */ 

memcpy((void *) &gqdtPtr->qdbspcsize, usrSpcPtr, 
sizeof (qdtPtr-—>qdbspcsize) ); 

#ifdef QQDEBUG 
printf("qdt size = %ld\n", qdtPtr->qdbspcsize) ; 


#endif 
/* Move up the user space pointer */ 
usrSpcPtr = (_SPCPTR) ((char *) usrSpcPtr + 16); 


/* Write the QDT itself out */ 


memcpy((void *) qdtPtr, usrSpcPtr, qdtPtr-—>qdbspcsize) ; 
return (qdtPtr->qdbspcsize) ; 


/* loadAccessPlan(access plan, userspace name) 

—- loads an access plan from a *USRSPC object */ 
long loadAccessPlan(ACCPLN_T *accessPlan, char *name) 
{ 

Qus_SPCA_0100_t usrSpcAttr; 
_SPCPTR usrSpcPtr; 
error_code errcode; 


errcode.bytes_provided = 512; 
errcode.msgid[0] = (char) 0; 


/* Retrieve Space Pointer to the User Space */ 
QUSPTRUS (name, &usrSpcPtr, &errcode) ; 
if (errcode.msgid[0]) 
{ 
printf ("Retrieve Space Pointer to User Space FAILED!\n"); 
printf ("msgid = %7s\n", strcnv400(errcode.msgid, 
sizeof (errcode.msgid) )); 
return (0); 


} 


/* Retrieve Size of Access Plan */ 
QUSRUSAT (&usrSpcAttr, 
sizeof (Qus_SPCA_0100_t), 
"SPCA0100", 
name, 
é&errcode) ; 
if (errcode.msgid[0]) 
{ 
printf ("Retrieve User Space Attributes FAILED! \n"); 
printf ("msgid = %7s\n", strcnv400(errcode.msgid, 
sizeof (errcode.msgid) )); 
return (0); 
} 
#ifdef QQDEBUG 


else 

{ 
printf ("Original User Space Attributes\n"); 
printf ("Bytes Returned ==> $d\n",usrSpcAttr.Bytes_Returned) ; 
printf ("Bytes Available ==> %d\n",usrSpcAttr.Bytes_Available) ; 
printf ("Space Size ==> $d\n",usrSpcAttr.Space_Size) ; 
printf ("Auto Extend ==> $c\n", 


usrSpcAttr.Automatic_Extendability) ; 


#fendif 


/* Pull the access plan size out first */ 
memcpy((void *) &accessPlan->size, usrSpcPtr, 
sizeof (accessPlan->size) ); 
#ifdef QQDEBUG 
printf("AP size = %ld\n", accessPlan->size) ; 
#fendif 
/* Now move to the access plan itself (on 16 byte boundary) */ 
accessPlan->storagePtr = (_SPCPTR) ((char*) usrSpcPtr + 16); 


return (accessPlan->size) ; 
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Defining a Simple Query 
This QQQQRY API example defines a simple query to perform ordering. The following is the equivalent SQL: 


SELECT * FROM OPENFILE1 
ORDER BY LNAME 
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/* PROGRAM: QQAPI1 */ 
ag * / 
/* LANGUAGE: ILE C FOR OS/400 */ 
fs xf 
/* DESCRIPTION: THIS PROGRAM DEFINES A SIMPLE QUERY TO PERFORM */ 
/* ORDERING. ia 
iL * / 
/* APIs USED: QQQORY * if. 
/* * / 
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#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 
#include <recio.h> 
#include <qdbrtvfd.h> 
#include <qqqqry.h> 
#include "qqapi.h" 


/* get the record format from the file */ 
#pragma mapinc ("recfmt", "APIQQ/OPENFILE1 (OPENFILE1)","input","p z",,) 
#include "recfmt" 


main — start of the program 


Flow: 

— initialize variables 

— override to set up sharing 
build various QDT sections 

— build QDT with those sections 
— QQQOORY to run the query 

—- open the data path 

-— read the data and display it 
-— close the data paths 


+ F£ + + FF F FF F 
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/* record I/O variables */ 

_RIOFB_T *feedback; 

_RFILE *filel; 

APTQQ OPENFILE1 OPENFILE1 i t recBuf; 
int recCount = 0; 


/* Query variables */ 
DBUFCB_T ufcbBuf; 

har qdtBuf[QDT_SIZE]; 

har formatBuf [FORMAT_SIZE]; 
DBQH_T *qdtPtr; 

db_Qddfmt_t *formatPtr; 
DBOFHDR_T fileHdr; 

DBON_T fileSpec [MAX_FILES]; 
DBOKH_T orderByHdr; 

DBOKF_T orderByF1ld[MAX_ORDERBY] ; 
int formatSize; 

int fileSpecSize; 

int orderBySize; 

error_code errcod; 


LOR On On Cn On Omemem ©) 


errcod.bytes_provided = 512; 

/* initialize the pointers */ 

qdtPtr = (QDBOH T *) qdtBuf; 

formatPtr = (Qdb_Qddfmt_t *) formatBuf; 


/* initialize the headers */ 

initQDT(qdtPtr, QDBOTEMO, ON, ON, QDBOFINA, 0); 
initFile(&fileHdr, QDBOINNJ, QDBQMFOA) ; 
initOrderBy (&orderByHdr) ; 


/* set up override to allow sharing */ 
system("OVRDBF FILE(OPENFILE1) SHARE (*YES)"); 
/* Note: If level checking is not done 

(ie. no format on initUFCB) then 

the override above must specify LVLCHK(*NO) */ 


/* build the individual QDT sections */ 
fileSpecSize = addFile(&fileHdr, fileSpec, "“OPENFILEL", 
NULL, NULL, NULL); 


formatSize = getRecordFmt (formatPtr, FORMAT_SIZE, "OPENFILE1", 


NULL, NULL) ; 
orderBySize = addOrderBy (&0orderByHdr, orderByFld, "LNAME", 


/* initialize the UFCB */ 
initUFCB(&ufcbBuf, QO_INPUT, formatPtr); 


/* Now build the real QDT... */ 
addQDTsection(qdtPtr, (char *) &fileHdr, 
sizeof(fileHdr), &qdtPtr—>qdbqfilo); 


OFF) ; 


addQDTsection(qdtPtr, (char *) fileSpec, fileSpecSize, NULL); 


addQDTsection(qdtPtr, (char *) formatPtr, 
formatSize, &qdtPtr-—>qdbqfldo) ; 


addQDTsection(qdtPtr, (char *) &orderByHdr, sizeof (orderByHdr), 


&qdtPtr->qdbqkeyo) ; 


addQDTsection(qdtPtr, (char *) orderByFld, orderBySize, NULL); 


/* Finally, run the query! */ 


QQQORY ("RUNOQRY ", (char *) &ufcbBuf, gqdtBuf, NULL, NULL, 


&errcod) ; 
if (errcod.msgid[0]) 
{ 
printf ("API QQQORY failed\n"); 
printf ("msgid = %$7s\n", strcenv400(errcod.msgid, 
sizeof (errcod.msgid) )); 


/* Now access the data */ 
if ((filel = _Ropen("OPENFILE1", "rr riofb=N")) == NULL) 
{ 


printf("Error opening file\n"); 


exit (1); 
} 
/* Perform any record I/O here... */ 
_Rformat (filel, "“OPENFILE1 "); 
printf ("First name Last name State\n"); 
feedback = _Rreadn(filel, (void *) &recBuf, sizeof(recBuf), __DFT); 
while (feedback->num_bytes == sizeof (recBuf) ) 
{ 
recCountt++; 
printf ("%s ", strcenv400(recBuf.FNAME, sizeof (recBuf.FNAME) )); 
printf ("%s ", strcenv400(recBuf.LNAME, sizeof (recBuf.LNAMBE) )); 
printf("Ss\n", strcenv400(recBuf.STATE, sizeof (recBuf.STATE) )); 
feedback = _Rreadn(filel, (void *) &recBuf, 
sizeof (recBuf), __DFT); 


} 


printf("%d records selected\n", recCount) ; 


/* Close the file */ 
_Rclose(filel); 


/* close out the QDT file handle */ 
system("RCLRSC") ; 


Defining a Join Query 
This QQQQRY API example defines a join query. The following is the equivalent SQL: 


SELECT * FROM OPENFILE1 A, OPENFILE2 B 
WHERE STATE = 'AK' AND 
A.ACCTNUM = B.CUSTNUM 
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/* PROGRAM: QQAPI7 iva 
/* * / 
/* LANGUAGE: ILE C FOR OS/400 */ 
ps KY 
/* DESCRIPTION: THIS PROGRAM DEFINES A JOIN QUERY. */ 
/* * / 
/* APIs USED: QQQORY AY 
is * / 
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#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 
#include <recio.h> 
#include <qdbrtvfd.h> 
#include <qqqqry.h> 
#include "qqapi.h" 


/* get the record format from the file */ 
#pragma mapinc ("recfmt", "APIQQ/FORMAT1 (FORMAT1)","input","p z",,) 
#include "recfmt" 


/* main - start of the program 
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Flow: 

— initialize variables 

-— override to set up sharing 

— build various QDT sections 

— build QDT with those sections 
— QQQOORY to run the query 

—- open the data path 

-— read the data and display it 
-— close the data paths 


/* record I/O variables */ 
_RIOFB_T *feedback; 

_RFILE *filel; 
APTQQ_FORMAT1_FORMAT1_i t recBuf; 
int recCount = 0; 


/* Query variables */ 
QDBUFCB_T ufcbBuf; 
char qdtBuf[QDT_SIZE]; 
char formatBuf [FORMAT_SIZE]; 

char selectBuf [SELECT_SIZE]; 
QDBOQH_T *qdtPtr; 

Qdb_Qddfmt_t *formatPtr; 

QDBOS_T *selectPtr; 

QDBOFHDR_T fileHdr; 

QDBON_T fileSpec [MAX_FILES]; 
QDBQJHDR_T joinHdr; 

QDBQJUFLD_T joinSpec [MAX_JOINTESTS]; 
int formatSize; 

int fileSpecSize; 

int selectSize; 

int joinSize; 

error_code errcod; 


errcod.bytes_provided = 512; 
/* initialize the pointers */ 


qdtPtr = (QDBOH T *) qdtBuf; 
formatPtr = (Qdb_Qddfmt_t *) formatBuf; 
selectPtr = (QDBQS_T *) selectBuf; 


/* initialize the headers */ 
initQDT(qdtPtr, QDBOTEMO, ON, ON, QDBOFINA, 
initFile(&fileHdr, QDBQINNJ, QDBOQMFOA) ; 
initSelection(selectPtr) ; 
initJoin(&joinHdr) ; 


/* set up override to allow sharing */ 

system("OVRDBF FILE (OPENFILE1) SHARE (*YES) 

/* Note: If level checking is not done 
(ie. no format on initUFCB) then 


0); 


the override above must specify LVLCHK(*NO) */ 


/* build the individual QDT sections */ 

addFile(&fileHdr, fileSpec, "OPENFILE1", NU 

fileSpecSize = addFile(&fileHdr, fileSpec, 
NULL, NULL, NULL); 


LL, NUL 


LVLCHK (*NO) ") ; 


L, NULL); 


"OPENFII 


LE2", 


formatSize = getRecordFmt (formatPtr, FORMAT_SIZE, "FORMAT1", 


NULL, NULL); 


joinSize = addJoinTest (&joinHdr, joinSpec, 
"CUSTNUM" , 2, "EQ"); 
/* build selection test: STATE = 'AK' */ 


addSelectField(selectPtr, "STATE", 1); 


"ACCTNUM", 1, 


addSelectLiteral(selectPtr, ""AK'", 4); 
selectSize = addSelectOperator(selectPtr, QDBQEQ) ; 


/* initialize the UFCB */ 
initUFCB (&ufcbBuf, QO_INPUT, NULL); 


/* Now build the real QDT... */ 
addQDTsection(qdtPtr, (char *) &fileHdr, 

sizeof(fileHdr), &qdtPtr—>qdbqfilo); 
addQDTsection(qdtPtr, (char *) fileSpec, fileSpecSize, NULL); 
addQDTsection(qdtPtr, (char *) formatPtr, 

formatSize, &qdtPtr-—>qdbqfldo) ; 
addQDTsection(qdtPtr, (char *) &joinHdr, 

sizeof (joinHdr), &qdtPtr—>qdbqjoio) ; 
addQDTsection(qdtPtr, (char *) joinSpec, joinSize, NULL); 
addQDTsection(qdtPtr, (char *) selectPtr, 

selectSize, &qdtPtr-—>qdbqselo) ; 


/* Finally, run the query! */ 
QQQORY ("RUNOQRY ", (char *) &ufcbhbBuf, gqdtBuf, NULL, NULL, 
&e@rxrcod) ; 
if (errcod.msgid[0]) 
{ 
printf ("API QQQOQRY failed\n"); 
printf ("msgid = %7s\n", strcenv400(errcod.msgid, 
sizeof (errcod.msgid) )); 
} 
/* Now access the data */ 
if ((filel = _Ropen("OPENFILE1", "rr riofb=N")) == NULL) 
{ 


printf("Error opening file\n"); 


exit (1); 
} 
/* Perform any record I/O here... */ 
_Rformat (filel, "FORMAT1"); 
printf ("Last name Item name\n"); 
feedback = _Rreadn(filel, (void *) &recBuf, sizeof (recBuf), __DFT); 
while (feedback->num_bytes == sizeof (recBuf) ) 
{ 
recCountt++; 


printf("%s ", strcnv400(recBuf.LNAME, sizeof (recBuf.LNAME) )); 
printf("Ss\n", strcnv400 (recBuf. ITEMNAME, 
sizeof (recBuf.ITEMNAMB) ) ); 
feedback = _Rreadn(filel, (void *) &recBuf, 
sizeof (recBuf), __DFT); 
} 


printf("%d records selected\n", recCount) ; 


/* Close the file */ 
_Rclose(filel); 


/* close out the QDT file handle */ 
system("RCLRSC") ; 


Defining a Join Query with Selection, Grouping, and Ordering 


This QQQQRY API example defines a join query with selection, grouping, and ordering. The following is the equivalent SQL: 


SELECT LNAME, FNAME, ITEMCODE, ITEMNAME, STATUS 
FROM OPENFILE1, OPENFILE2 

WHERE STATE = 'AK' AND CUSTNUM = ACCTNUM 
GROUP BY LNAME, FNAME, ITEMCODE, ITEMNAME, STATUS 
ORDER BY ITEMNAME 
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/* 


PROGRAM: QQAPI11 


LANGUAGE: ILE C FOR OS/400 


DESCRIPTION: THIS PROGRAM DEFINES A JOIN QUERY WITH SELECTION 


GROUPING AND ORDERING. 


APIs USED: QQQORY 


xf 
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#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 
#include <qdbrtvfd.h> 
#include <qqqqry.h> 
#include "qqapi.h"> 
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main — start of the program 


Flow: 

— initialize variables 

— override to set up sharing 

— build various QDT sections 

— build QDT with those sections 
— QQQOORY to run the query 

—- open the data path 

-— read the data and display it 
-— close the data paths 


/* file I/O variables */ 


#define REC_SIZE 52 


FILE *filel; 
char recBuf [REC_SIZE]; 
int recCount = 0, found; 


/* Query variables */ 
QDBUFCB_T ufcbBuf; 
char qdtBuf [QDT_SIZE]; 
char formatBuf [FORMAT_SIZE]; 
char tempFormatBuf [FORMAT_SIZE]; 
char selectBuf [SELECT_SIZE]; 
DBQH_T *qdtPtr; 

db_Qddfmt_t *formatPtr; 
db_Qddfmt_t *tempFormatPtr; 
DBQS_T *selectPtr; 

DBOFHDR_T fileHdr; 

DBON_T fileSpec [MAX_FILES]; 
DBQJHDR_T joinHdr; 


DBOKH_T orderByHdr; 

DBOGH_T groupByHdr; 

DBOKF_T orderByF1ld[MAX_ORDERBY] ; 
DBOGF_T groupByF1d[MAX_GROUPBY]; 
int formatSize; 

int fileSpecSize; 

int orderBySize; 

int groupBySize; 

int selectSize; 
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DBOQJFLD_T joinSpec [MAX_JOINTESTS]; 


int joinSize; 
error_code errcod; 


memset( (void *) &errcod, (char) 0, sizeof(error_code) ); 
errcod.bytes_provided = 512; 

/* initialize the pointers */ 

qdtPtr = (QDBOH T *) qdtBuf; 

formatPtr = (Qdb_Qddfmt_t *) formatBuf; 

tempFormatPtr = (Qdb_Oddfmt_t *) tempFormatBuf; 

selectPtr = (QDBQS_T *) selectBuf; 


/* initialize the headers */ 

initQDT(qdtPtr, QDBOTEMO, ON, ON, QDBOFINA, 0); 
initFile(&fileHdr, QDBOQINNJ, QDBOQMFOA) ; 
initFormat (formatPtr, "JOINFMTO1"); 

initOrderBy (&orderByHdr) ; 

initGroupBy (&groupByHdr) ; 
initSelection(selectPtr) ; 

initJoin(&joinHdr) ; 


/* set up override to allow sharing */ 
system("OVRDBF FILE(OPENFILE1) SHARE (*YES) LVLCHK(*NO)"); 
/* Note: If level checking is not done 
(ie. no format on initUFCB) then 
the override above must specify LVLCHK(*NO) */ 


/* build the individual QDT sections */ 
addFile(&fileHdr, fileSpec, "OPENFILE1", NULL, NULL, NULL); 
fileSpecSize = addFile(&fileHdr, fileSpec, "“OPENFILE2", 
NULL, NULL, NULL); 
/* get the first format and copy some fields */ 
getRecordFmt (tempFormatPtr, FORMAT SIZE, “OPENFILE1", 
NULL, NULL) ; 
copyField(formatPtr, "LNAME", 1, tempFormatPtr); 
copyField(formatPtr, "FNAME", 1, tempFormatPtr); 
/* clear the old format data */ 
memset (tempFormatPtr, 0, FORMAT SIZE); 
/* get the second format and copy some more fields */ 
getRecordFmt (tempFormatPtr, FORMAT SIZE, “OPENFILE2", NULL, NULL); 
copyField(formatPtr, "ITEMCODE", 2, tempFormatPtr); 
copyField(formatPtr, "ITEMNAME", 2, tempFormatPtr); 
formatSize = copyField(formatPtr, "STATUS", 2, tempFormatPtr) ; 
/* set all the fields to input only */ 
setFieldUsage(formatPtr, NULL, 1); 
/* build selection test: STATE = 'AK' */ 
addSelectField(selectPtr, "STATE", 1); 
addSelectLiteral(selectPtr, ""AK'", 4); 
selectSize = addSelectOperator(selectPtr, QDBQEQ) ; 
joinSize = addJoinTest (&joinHdr, joinSpec, "ACCTNUM", 1, 
"CUSTNUM" , 2, "EQ"); 
orderBySize = addOrderBy (&orderByHdr, orderByFld, 
"ITEMNAME", OFF) ; 
addGroupBy (&groupByHdr, groupByFld, "LNAME", 0); 
addGroupBy (&groupByHdr, groupByFld, "FNAME", 0); 
addGroupBy (&groupByHdr, groupByFld, "ITEMCODE", 0); 
addGroupBy (&groupByHdr, groupByFld, "ITEMNAME", 0); 
groupBySize = addGroupBy (égroupByHdr, groupByFld, "STATUS", 0); 


/* initialize the UFCB */ 

initUFCB (&ufcbBuf, QO_INPUT, NULL); 

/* set up for sequential only processing since it is a group by */ 
ufcbBuf.qufcb.parameter.seqonly = SEQUPROC; 
ufcbBuf.qufcb.parameter.seqonoff = ON; 
ufcbBuf.qufcb.parameter.numonoff = ON; 
ufcbBuf.qufcb.parameter.numrecs = 1; 


/* Now build the real QDT... */ 
addQDTsection(qdtPtr, (char *) &fileHdr, 
sizeof(fileHdr), &qdtPtr-—>qdbqfilo); 
addQDTsection(qdtPtr, (char *) fileSpec, fileSpecSize, NULL); 
addQDTsection(qdtPtr, (char *) formatPtr, 
formatSize, &qdtPtr-—>qdbqfldo) ; 
addQDTsection(qdtPtr, (char *) &joinHdr, 
sizeof (joinHdr), &qdtPtr—>qdbqjoio) ; 
addQDTsection(qdtPtr, (char *) joinSpec, joinSize, NULL); 
addQDTsection(qdtPtr, (char *) selectPtr, 
selectSize, &qdtPtr-—>qdbqselo) ; 
addQDTsection(qdtPtr, (char *) &o0rderByHdr, sizeof (orderByHdr), 
&qdtPtr->qdbqkeyo) ; 
addQDTsection(qdtPtr, (char *) orderByFld, orderBySize, NULL); 
addQDTsection(qdtPtr, (char *) &groupByHdr, sizeof (groupByHdr), 
é&qdtPtr->qdbaqgrpo) ; 
addQDTsection(qdtPtr, (char *) groupByFld, groupBySize, NULL); 
/* Finally, run the query! */ 
QQQORY ("RUNOQRY ", (char *) &ufcbBuf, gqdtBuf, 
NULL, NULL, &errcod); 
if (errcod.msgid[0]) 


{ 
printf ("API QQQOQRY failed\n"); 
printf ("msgid $7s\n", strcenv400(errcod.msgid, 
sizeof (errcod.msgid) )); 


} 


/* Now access the data */ 


if ((filel = fopen("OPENFILE1", "rb")) == NULL) 
{ 
printf("Error opening file\n"); 
exit (1); 
} 
/* Perform any record I/O here... */ 
printf("Last name First name Code \ 
Item St\n"); 
found = fread((void *) &recBuf, REC_SIZE, 1, filel); 
while (found) 
{ 
recCountt+t+; 
printf("%Ss ", strcnv400(recBuf, 15)); 
printf("%Ss ", strcenv400(&recBuf[15], 10)); 
printf("%Ss ", strcenv400(&recBuf[25], 5)); 
printf("%Ss ", strcenv400(&recBuf[30], 20)); 
printf("Ss\n", strcenv400(&recBuf[50], 2)); 
found = fread((void *) &recBuf, REC_SIZE, 1, filel); 


} 


printf("%d records selected\n", recCount) ; 


/* Close the file */ 
fclose(filel); 


/* close out the QDT file handle */ 
system("RCLRSC") ; 


Generating and Sending an Alert 


The following ILE RPG program uses both alert APIs. 


H 
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D * 
D* Program Name: ALERTS 


D * 

D* Programming Language: ILE RPG for OS/400 

D * 

D* Description: This program uses alert APIs. First, it 

D* calls the Generate Alert (QALGENA) API to 
D* generate an alert without sending a message 
D* to QSYSOPR or QHST message queue. Then it 
D* uses the Send Alert (QALSNDA) API to send 
D* the alert to the 0OS/400 alert manager. 

D * 


D* Header Files Included: QUSEC - Error Code Parameter 

D * 

D * I I KK KK 
D * eK ee I I ee KK KK 
D * 

D* Error Code parameter include 


D * 

D/COPY QSYSINC/QRPGLESRC, QUSEC 

D * 

D * 

D* Miscellaneous data structure 

D * 

DRCVVAR Ss 512. 

DRCVLEN Ss 9B 0 INZ(%SSIZE(RCVVAR) ) 
DALERT_SIZE Ss 9B 0 

DMSG_FILE Ss 20 INZ ('QCPFMSG QSYS"') 
DMSG_ID Ss 7 INZ('CPA2601"') 
DMSG_DATA Ss 100 

DMSG_SIZE Ss 9B 0 INZ(0) 
DALERT_TYPE S 1 INZ('L"') 
DORIGIN Ss 10 INZ('ALERTS"') 
c* 

C* Beginning of mainline 

c* 

C* Set error handling 

c* 

Cc EVAL QUSBPRV = %SIZE (QUSEC) 
c* 


C* Start by generating an alert for a specific message 


Cc CALL "QALGENA' 

Cc PARM RCVVAR 

c PARM RCVLEN 

Cc PARM ALERT_SIZE 
Cc PARM MSG_FILE 

C PARM MSG_ID 

1S: PARM MSG_DATA 

c PARM MSG_SIZE 
Cc PARM QUSEC 

c* 

c* If no error reported, send the generated alert 

c* 

Cc QUSBAVL IFEQ 0) 

Cc CALL "QALSNDA' 

€ PARM RCVVAR 

Cc PARM ALERT_SIZE 
Cc PARM ALERT_TYPE 
Cc PARM ORIGIN 

ic PARM QUSEC 

c* 

C* If error on send, then display the error message 

c* 

€ QUSBAVL IFNE 0) 

ie QUSEI DSPLY 


Cc END 


C* If error on generation, then display the error message 


c* 
e; ELSE 

Cc QUSEI DSPLY 

Cc END 

c* 

Cc EVAL *INLR = ‘1! 
Cc RETURN 

c* 

cC* End of MAINLINE 

cx 


Diagnostic Reporting 


The following example program illustrates the use of the Send Nonprogram Message API, QMHSNDM, the Receive Program 
Message API, QMHRCVPM, and the Change Exception Message API, QMHCHGEM. The program produces a diagnostic report of 
errors that occur when the QMHSNDM API is used to send a message to more than one message queue. 


The program calls the QMHSNDM API to send a message to message queues that do not exist. The QMHSNDM API returns a 
generic exception message, CPF2469. This message indicates that the API also returned one or more diagnostic messages describing 
the errors. After the program receives the exception message and verifies that it is message CPF2469, it uses the QMHCHGEM API 
to handle the exception message. The QMHRCVPM API is used to receive the diagnostic messages. The program prints the 
exception message, the diagnostic messages, and the message help. 


Diagnostic Report (DIAGRPT) Program 


[BORK RK KK KK KK KR IA IA IA IA I AA AAA A A A I a I a / 


a Kf. 
/* MODULE NAME: DIAGRPT - Diagnostic Report */ 
/* LANGUAGE: ILE C for OS/400 * 
LF Kf 
/* FUNCTION: This module will produce a diagnostic report that */ 
ia could be used in diagnosing the errors that */ 
/* occurred using the QMHSNDM API to send a message */ 
/* to multiple message queues. aA 
/* */ 
/* This program purposely causes the QMHSNDM API to */ 
bs try to send a message to message queues that do */ 
/* not exist. As a result, the generic CPF2469 ae A 
/* exception is returned indicating that one or more */ 
f% diagnostic messages were returned identifying the */ 
ce error(s) on the send operation. */ 
Ps #Y, 
/* The program looks for and handles the CPF2469 */ 
/* exception. It then receives and prints out the eA 
asi exception and the previous diagnostics. as 
pF Hof. 
/* Dependency: A print file must be created before calling * / 
/* program DIAGRPT. The print file should be created */ 
/* using the following command: */ 
aa *f 
/* CRTPRTF FILE(PRTDIAG) CTLCHAR (*FCFC) */ 
‘ha CHLVAL((1 (13))) */ 


[KK RK KK KK KK KI IA AA IA IA I I A AA AA AA A A I a I I / 


#include <stdio.h> 
#include <stdlib.h> 
#include <signal.h> 
#include <string.h> 
#include <except.h> 
#include <qmhchgem.h> /* From QSYSINC/H *f 


#include <qmhrcvpm.h> /* From QSYSINC/H */ 
#include <qmhsndm.h> /* From QSYSINC/H band 
#include <qusec.h> /* From QSYSINC/H mf 


#define DIAG_TYPE "02" 
#define BUF_SIZE 80 


[ORK RK KK KKK KK I AA A A A A A A A IA AA A A A A A I I / 


/* Type definition for error code structure * 
KKEKKKKK KKK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKEKKKKKAEKK 
/ / 


typedef struct error_code_struct 
{ 
Qus_EC_t ec_fields; 
char Exception_Data[100]; 
} error_code_struct; 


[KK RK KK KK KK KK I A A A A A A A IA IA AA A A A A I I / 


/* Type definition for qualified name structure Y 
[BORK RK KK KK KK KK A A A A A A A RIA AA A A A A A I I / 


typedef struct qual_name_struct 
{ 
char name[10]; 
char libr[10]; 
} qual_name_struct; 


[ORK RK KK KK KK KK KK IK IA A A A A A A A IA AA A A A AI I I I / 


/* Type definition for message information structure used on the *y. 
/* receive. F is the fixed portion of the record and V is the */ 
/* variable length portion of the record. */ 


[KK RK KK KK KKK IK IA A A A A A A A A A A A A a I I / 


typedef struct msg_info_struct 
{ 
Qmh_Rcvpm_RCVM0200_t F; 
char V[1200]; 
} msg_info_struct; 


FILE *prtf; 

char buf[80]; 

char received[7]; 

int exception_count; 


[BKK RK KK KKK KK I A A A A RA A A IR AA A A A A A I I / 


/* Function to handle errors received on the API calls. ays 
[KK RK KK KK KK KK KK AA A A A RA A IA IA A A A A I A I I / 


static void excp_handler(_INTRPT_Hndlr_Parms_T *excp_info) 
{ 


error_code_struct Error_Code; 


/* If the exception is CPF2469, increment the exception counter, */ 
/* and mark the exception as handled by the QMHCHGEM API */ 


if (strncmp (excp_info->Msg_Id, "CPF2469",7) == 0) { 
memcpy (received, (excp_info->Msg_Id),7); 
exception_count++; 
QMHCHGEM (& (excp_info->Target), 0, 
(char *) (& (excp_info->Msg_Ref_Key)), 
"* HANDLE ", "", 0, &Error_Code) ; 


[ORK RK KK KKK KK KK KR IA IA IA I I AA A AA AA IA A a I I / 


/* BuildQList: Routine to build the message queue list. LWA 
[KKK KK KK KK KKK IA AA IA A I I A AAA IA A A a I I / 


void BuildQList( qual_name_struct *QueueList, int NumQueue) 


{ 


int i; 


strncpy (QueueList [0] .name, "OQPGMR ",10); 
strncpy (QueueList [1] .name, "SNOOPY ie 0 
strncpy (QueueList [2] .name, "QSECOFR ",10); 
strncpy (QueueList [3] .name, "PEANUTS Wy lO!) =; 
strncpy (QueueList [4] .name, "QUSER We 0.0).% 
for (i = 0; i < NumQueue ; it+ ) 

{ 

strncpy (QueueList [i].libr, "*LIBL 1:0) ¥ 


} 


[ORK RK KK KKK KK KKK A IA AA IA I I I A AAA AAA IA A a I I / 


/* PrintError: Routine to print error information and exit. */ 
[OK KK KK KKK KKK KR IK AA IA IA A AAA AA A A I A I I / 
void PrintError(char *errstring, char exception[7]) 


{ 


memset (buf, ' ',BUF_SIZE); 

buf[0] = '0'; 

strncpy (buft+l,errstring, strlen(errstring) ); 
fwrite (buf,1,BUF_SIZE,prtf); 


memset (buf, ' ',BUF_SIZE) ; 

buf[0] = '0'; 

strncpy (buf+1,"Exception received-—->", 20); 
strncpy (buf+21,exception, strlen (exception) ); 
fwrite (buf,1,BUF_SIZE,prtf); 

fclose(prtf); 

exit (1); 


[ORK RK KK KK KKK KK IA IA AA IA I I A A AA IA IA A a I A / 


/* PrintData: Routine to print varying length character string data.*/ 
[ORK RK KK KKK KK KKK IR AA IA A I I A A AA IA AA A A a / 
void PrintData(char *strname, void *strptr, int strlgth) 
{ 

char *strdata = strptr; 

int i,lgth,remain; 


/* Write the description and the data that will fit on one line */ 
memset (buf, ' ',BUF_SIZE) ; 

buf[0] = '0'; 

lgth = strlen(strname) ; 

strncpy (buf+1,strname,lgth) ; 

lgth++; 


/* remain = MIN(strlgth,80 - lgth) */ 

remain = (strlgth < 80 - lgth) ? strlgth : 80 - lgth; 
strncpy (buft+tlgth, strdata, remain) ; 

fwrite (buf,1,BUF_SIZE,prtf); 


/* Now write the remainder of the data */ 

if (strlgth > (80 - lgth )) 
{ 
/* Adjust pointer to data not printed yet */ 
strdata = strdata + (80 - lgth); 


for (i = O; i < strlgth; i = i+ 70, strdata = strdata + 70 ) 
{ 
/* lgth = MIN(strlgth-i,70) */ 
lgth = (strligth-i < 70) ? strlgth-i : 70; 


memset (buf,' ',BUF_SIZE); 

strncpy (buf, "0 MeO) 7 
memcpy (buf+10, strdata,lgth); 
fwrite (buf,1,BUF_SIZE,prtf); 


[BORK RK KK KKK KK KK IK IA IA A I I A A AAA A A A a I I / 


/* PrintMessage: Routine to print the message data and text. hele 
[ORK RK KK KKK KKK KK IR IA IA IA I I A A AA AA AA IA A I Ie a / 


void PrintMessage(msg_info_struct *Msg) 


{ 
char *DataPtr; /* Pointer to the varying length character data*/ 
int DataLen; /* Length of the varying length character data */ 
char CharType[10]; /* Message type as a string */ 


PrintData("Message ID->",Msg—->F.Message_Id,7); 
/* Convert Message Type to a character string to be printed out */ 
if (memcmp (Msg->F.Message_Type, "02",2) ==0) 
strncpy (CharType,"DIAGNOSTIC", 10); 
else if (memcmp (Msg->F.Message_Type,"15",2) ==0) 
strncpy (CharType, "ESCAPE ",10); 
PrintData("Message Type->",CharType,10); 


/* First point to the beginning of the message data */ 

/* in the structure and get the length of data returned. */ 

DataPtr = Msg->V; 

DataLen = Msg->F.Length_Data_Returned; 

/* If there is non-blank data, print it out */ 

if ((DataLen > 0) && (strspn(DataPtr," ") < DataLen) ) 
PrintData("Message data received->",DataPtr,DataLen) ; 


/* Point to the beginning of the message text field and get the */ 

/* length of message text returned. Kf 

DataPtr += DataLen; 

DataLen = Msg->F.Length_Message_Returned; 

/* If there is non-blank text, print it out */ 

if ((DataLen > 0) && (strspn( DataPtr," ") < DatalLen) ) 
PrintData("Message text received->",DataPtr,DataLen) ; 


/* Now update to point to the beginning of the message */ 
/* help text field and get the length of message help text Ref 
/* returned. #7 


DataPtr += DataLen; 
DataLen = Msg->F.Length_Help_Returned; 


/* If there is non-blank message help text, print it out aA 

if ((DataLen > 0) && (strspn( DataPtr," ") < DatalLen) ) 
PrintData("Message help text received->",DataPtr,DataLen) ; 

strncpy (buf, "- ",43); 


fwrite (buf,1,BUF_SIZE,prtf); 


[KOK KKK KK KK IR IA A I A AA AA IA IA AA A I I I I I / 


px Rif 
/* Start of main program. eee 
[* Kf 


[KOK KKK KK KK IA IA A A AA AA IA AA A A I I I / 


main () 


{ 


error_code_struct ErrorCode; 


qual_name_struct 
qual_name_struct 
qual_name_struct 


msg_info_struct 


MsgQLlist [5]; 
MsgFile; 
RpyMsgQ; 


MsgInfo,; 


char MsgData[128] 
char MsgText[512]; 
char MsgHelp[512] 
char PgmMsgQ[10]; 
char MsgType[10]; 
char MsgAction[10]; 
char Format [8]; 
char MsgId[7]; 
char MsgKey[4]; 


int MsgTextLen; 
int MsgInfoLen; 
int NumMsgQ; 
int PgmCount; 
int WaitTime; 
int morediag; 


/* Initialize variables */ 
exception_count = 0; 

memcpy (ErrorCode.ec_fields.Exception_Id," 
ErrorCode.ec_fields.Bytes_Provided = 0; 


memcpy (MsgId," eee ae 

memcpy (MsgFile.name," ",10); 
memcpy (MsgFile.libr," U7 10))7 
strcpy (MsgText,"This is an immediate, 


MsgTextLen = strlen(MsgText) ; 


informational message") ; 


memcpy (MsgType, "* INFO Mig LO.) 5 
memcpy (RpyMsgQ.name," ",10); 
memcpy (RpyMsgQ.libr," ",10); 


/* Build the list of message queues to send the message to 
NumMsgQ = 5; 
BuildQList (MsgQList,NumMsgQ) ; 


/* Enable the exception handler around the call to QMHSNDM 
#pragma exception_handler(excp_handler, 0, 0, _C2_MH_ ESCAPE) 


/* Send the message to the list of message queues. 
QMHSNDM( MsgId, 
éMsgFile, 
MsgText, 
MsgTextLen, 
MsgType, 
éMsgQList, 
NumMsgQ, 

& RpyMsgQ, 
&MsgKey, 
&ErrorCode) ; 


/* Disable the exception handler 
#pragma disable_handler 


/* If an error occurred on the send, produce an exception report 
/* identifying what errors occurred. 
if (exception_count != 0) 


{ 


* 


aes 


xf 


ne 


*f 
if: 


/* Open printer file using first character forms control and 
/* write the header information. 

prtf = fopen ("PRIDIAG", "wh type=record recfm=FA lrec1l=80"); 
memset (buf, ' ',BUF_SIZE); 


strncpy (buf, "1 DIAGNOSTIC REPORT", 43); 
fwrite (buf,1,BUF_SIZE, prtf) ; 
strncpy (buf," 43) 3 
fwrite (buf,1,BUF_SIZE, prtf) ; 
strncpy (buf, "- ",43); 


fwrite (buf,1,BUF_SIZE, prtf) ; 


/* Do the setup to first receive the exception signalled. 
memcpy (Format, "RCVM0200", 8) ; 


memcpy (PgmMsgQ, "* ",10); 
memcpy (MsgType, "*EXCP WF 10!) <7 
memcpy (MsgKey, " ",4); 

memcpy (MsgAction, "*OLD "109%; 
PgmCount = 0; 

WaitTime = 0; 


MsgInfoLen = 1276; 


mf: 
if 


iad 


/* Now change bytes_provided to 116 so that if any errors occur */ 
/* on the receive, the error information will be returned in the*/ 


/* error code structure instead of generating more exceptions 
/* which will clutter up the program message queue. 
ErrorCode.ec_fields.Bytes_Provided = 116; 


/* Receive the last exception type message on the program 

/* message queue 

QMHRCVPM (&MsgInfo, 
MsgInfoLen, 
Format, 
PgmMsgQ, 
PgmCount, 
MsgType, 
MsgKey, 
WaitTime, 
MsgAction, 
&ErrorCode) ; 


/* Test for any errors on the receive */ 
if (ErrorCode.ec_fields.Bytes_Available > 0) 
{ 
PrintError ("QMHRCVPM — Did not complete successfully", 
ErrorCode.ec_fields.Exception_Id) ; 


/* An exception message was received successfully. Now see if 


aA 
as 


avd 


ay 


/* the message received is the same exception that was signalled*/ 


/* If not, there is an error. 
if (strncmp (MsgInfo.F.Message_Id, received,7) != 0) 
{ 
PrintError ("QMHRCVPM — Wrong exception received", 
MsgInfo.F.Message_Id) ; 


/* The exception message was received successfully. 
/* Print the message data and text for the exception message. 
PrintMessage(&MsgInfo) ; 


/* If the message was the generic CPF2469, there are one or 


/* more diagnostic messages to go with the CPF2469 on the queue. 


ef 


xy 
eh 


if 
oh 


/* Receive the diagnostic messages previous to the CPF2469 until*/ 


/* a non-diagnostic message is received or there are no more 
/* messages. 
if (strncmp (MsgIiInfo.F.Message_Id, "CPF2469",7) == 0) 


wes 
/- 


{ 

memcpy (MsgType, "*PRV ",10); 

memcpy (MsgKey,MsgInfo.F.Message_Key, 4) ; 
morediag = 1; 


while (morediag) 

{ 

/* Receive the previous diagnostic */ 

QMHRCVPM (&MsgInfo, 
MsgInfoLen, 
Format, 
PgmMsgQ, 
PgmCount, 
MsgType, 
MsgKey, 
WaitTime, 
MsgAction, 
&ErrorCode) ; 


/* Test for error on the receive */ 
if (ErrorCode.ec_fields.Bytes_Available > 0) 
{ 
PrintError ("QMHRCVPM — Did not complete successfully", 
ErrorCode.ec_fields.Exception_Id); 


} 


/* If bytes available = 0 OR the next message is not a aA 
/* diagnostic message, we are done. */ 
if ((MsgInfo.F.Bytes_Available == 0) | | 

(strncmp (MsgIinfo.F.Message_Type,DIAG_TYPE,2) != 0) ) 


{ 


morediag = 0; 


else /* A diagnostic was received */ 


{ 


/* Print the message data and text for the diagnostic */ 
/* message */ 
PrintMessage (&MsgInfo); 


/* Now copy the message key of the diagnostic message */ 
/* received to the MsgKey parameter to use on the next */ 
/* call to QMHRCVPM. Ay, 
memcpy (MsgKey,MsgInfo.F.Message_Key,/7); 
} /* End of while morediag = 1 i 
} /* End of if CPF2469 received aif 
/* Write trailer */ 
memset (buf, ' ',BUF_SIZE); 
strncpy (buf, "- END OF DIAGNOSTIC REPORT", 48) ; 
fwrite (buf,1,BUF_SIZE, prtf) ; 


/* Close the print file */ 
fclose(prtf); 


/* End of if error on send xf 


/* End mainline #Y: 


Printed Diagnostic Report 
The DIAGRPT program produces a report like this: 


Message ID->CPF2469 

Message Type->ESCAPE 

Message text received->Error occurred when sending message. 

Message help text received->Recovery ...: See messages 
previously listed for a description of the error. 
Correct the error, and then try the 
command again. 


Message ID->CPF2403 

Message Type->DIAGNOSTIC 

Message data received-—>PEANUTS *LIBL 

Message text received->Message queue PEANUTS in *LIBL not found. 


Message help text received->Cause ... ace The message queue you 
specified was not found in the renee you specified. One 
of the following occurred: -- The queue name was not 
entered correctly. -—- The queue does not exist in the 
specified library. -- You specified the wrong library name. 
Recovery ... : Do one of the following and try the 
request again: -- Correct or change the message queue 


name or library name used in the message queue (MSGQ) 
parameter or the to-message queue (TOMSGQ) parameter. 
—- Create the message queue using the Create Message 
Queue (CRIMSGQ) command. 


Message ID->CPF2403 
Message Type->DIAGNOSTIC 


Message data received-—>SNOOPY *LIBL 

Message text received->Message queue SNOOPY in *LIBL not found. 

Message help text received->Cause ... aes The message queue 
you specified was not found in “ene library you specified. 
One of the following occurred: -- The queue name was not 
entered correctly. -- The queue does not exist in the 
specified library. -- You specified the wrong library 
name. Recovery ...: Do one of the following and 
try the request again: -- Correct or change the message 


queue name or library name used in the message queue 
(MSGQ) parameter or the to-message queue (TOMSGQ) 
parameter. -—-— Create the message queue using the Create 
Message Queue (CRIMSGQ) command. 

End of Diagnostic Report 


Listing Directories 


You should call this program with only one parameter, the parameter that represents the directory you want to list. 


[KK RK KKK KK KK A IA A A AR A RR IA A AA A I a I / 
[OK KK KKK KK KKK AR IA A A A AR A IA A A A A I I / 


/* FUNCTION: This program lists a directory to a spooled file. */ 
/* */ 
/* LANGUAGE: ILE C * 

LA */ 
ie +). 
/* APIs USED: QHFOPNDR, QHFRDDR, QHFCLODR, QHFLSTFS, QUSCRTUS, */ 
if QUSRTVUS #7 
[% */ 


[ORK RK KK KK KKK A A A A A A A RA AA A A A A I I / 
[KK RK KKK KK KK KK A A A A A A A A IA AA AA A A A A I / 


ie ee ee ee ee ee ee ee ee ee a ee fb 


/* INCLUDE FILES */ 
[BORK RK KK KK KK KA A A A A A A RR AA A AA A A a a I / 
#include <stdio.h> 

#include <stdlib.h> 

#include <string.h> 

#include <qhfopndr.h> 

#include <qhfrddr.h> 

#include <qhfclodr.h> 

#include <qhflstfs.h> 

#include <quscrtus.h> 

#include <qusrtvus.h> 

#include <qusec.h> 


[ORK RK KK KK KK KR I A A A A A A A A IA A A A A A a I / 


/* STRUCTURE AND VARIABLE DECLARATIONS «7; 


eee ee ee ee ee ee a ee ee ee f 


eee ee ee ee ee i ee ee a a a ef 


/* Parameters for QHFOPNDR */ 
[ORK RK KKK KK KK AK IA A A A A A A A A A A A A A I a I / 
char dir_handle[16]; /* Directory handle ca: 
int namelen; /* Length of path name */ 
char openinfo[6]; /* Open information */ 


typedef struct { 
Qhf_Attr_Selec_Tbl_t fixed; 


int offset2; 

int offset3; 

int att_lenl; 
char att_namel [8]; 
int att_len2; 
char att_name2 [8]; 
int att_len3; 
char att_name3[8]; 


} selection_struct; 


selection_struct select; 
int selectionlen; 


[OK KK KKK KK KK IR A A A I A A A A IA AA A A A A I I I / 


/* Error Code Structure *f 
ig */ 
/* This shows how the user can define the variable length portion */ 
/* of error code for the exception data. */ 
Ls ¥y. 


[BORK RK KKK KK KK IK IA A A I A A A A IA AA AA A A I I / 


typedef struct { 
Qus_EC_t ec_fields; 
char Exception_Data[100]; 
} error_code_t; 


error_code_t error_code; 


[OK KK KR KK KK KK KK IA A AI A A A A IA A AA A A I I I / 


/* Parameters for QHFRDDR */ 
[OK KK KK KK KKK A A A A A A A A A AA A A A A I I I / 
/* The directory handle is the same as for QHFOPNDR * / 


typedef struct { 
Qhf_Data_Buffer_t fixed; 


int num_att; 
int offsets[4]; 
char attinfo[276]; 


} read_buffer; 


read_buffer buffer; 


int result_count; 
int bytes_returned; 


[KK RK KK KKK KK I A A A A A A A IA A AR A A A I I / 


/* Parameters for QHFCLODR */ 
[ORK RK KK KKK KKK IK IA A A I A A RR IA A A A I I I / 


/* No additional ones need to be declared *y/ 


[ORK RK KKK KKK KK A IA A A A RR A IA IA A A A A I I a I / 


/* Parameters for QUSCRTUS */ 


[ORK RK KKK KK KKK I A A A A RR A A A A A A A I I I / 
int size; 
char text [50]; 


[OK KK KKK KK KK I A A A A A A A A IA A A A A I I I / 


/* Parameters for QHFLSTFS ewe 
ee ee a ee ee ee ee a ee a a ee f 


/* No additional ones need to be declared ay 


[ORK RK KKK KK KK IK A A A I A A A IA A A A A A I I I / 


/* Parameters for QUSRTVUS */ 
[OK KKK KK KK KKK IA A A A I A A A A AA A A A A a I / 
int startpos; 

int len; 

char charbin4 [4]; 

char FSname[10]; 


[KK RK KKK KK KK IR IA A A A A A A IA A A A A A A I / 


/* Other declarations */ 
[OK KK KK KK KK IR A A A A A A A A AA A A A A I I I / 


int entrypos; 
int numentries; 
int entrylen; 


char *att; 

char name [100]; 
char attname [30] 
char attval[30]; 


~ 


int attnamelen; 
int attvallen; 
char newname [30]; 
int filesize; 


char fileatt [10] 


~ 


typedef struct { 


char century; 
char year[2]; 
char month[2]; 
char day[2]; 
char hour[2]; 
char minute [2]; 
char second[2]; 


} charval; 
charval chartime; 


int bytes_used; 
int 1} 


main(int argc, char *argv[]) 


{ 
char write_string[100]; 
FILE *stream; 


error_code.ec_fields.Bytes_Provided = 0; 


[ORK RK KK KK KK I A A A I A A A A AO I / 


/* Make sure we received the correct number of parameters. The */ 


/* argc parameter will contain the number of parameters that */ 
/* was passed to this program. This number also includes the af 


/* program itself, so we need to evaluate argc-l. *Y. 
KEKKKK KK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKKKKKKKKKKKKKKEK 
/ / 


if (((arge - 1) <1) || ((arge - 1 > 1))) 

[ORK KK RK KK KK A I A A A A I A A A A A A A A e/ 
/* We did not receive all of the required parameters, or */ 
/* received too many. Exit from the program. *f 


[BORK RK KK KK KK A A A A I I I A A A A A A I / 


{ 
exit (1); 


[ORK RK KK KK KK A A A A A I A A A A A A OA A A I e/ 


/* Open QPRINT file so that data can be written to it. If the */ 


/* file cannot be opened, print a message and exit. */ 
[ORK RK KK KK KK A A A I I I A A A A I A A I / 
if((stream = fopen("QPRINT", "wb")) == NULL) 


{ 
printf("File could not be opened\n"); 


exit (1); 
} 
memset (name, ' ', 100); 
memcpy (name, argv[1], 100); 
if (!memcmp(name, " ", 1)) 


{ 

memcpy (name, "ROOT", 4) ; 

fprintf(stream,"Directory listing for path %.100s\n", name); 
size = 1; 


memcpy (text, "temporary user space used by program DIR Gy 
Sica a ae aad ces ee eae lea eae eek 
/* Create the user space for QHFLSTFS to use. */ 
[ORK KK RK KK KK KK A A A A A A A A A A A I  e/ 
QUSCRTUS ("FSLST QTEMP ", "TEMPSPACE ", size, " ", 

"*USE Ww, text, “"*YES ", &error_code) ; 


[ORK RK KK KK KK A A A A A I I A A A A A OA A I e/ 


/* List the file systems into that space. ei 
[ORK RK KK KK KK KK I A A A I A A A A A OA A I / 
QHFLSTES ("FSLST QTEMP ", “HFSLO100", &error_code) ; 


[ORK RK KK KK KK I A A A A A I A A A A A AOA A A I / 


/* Get the starting point for the file system entries. */ 
[ORK RK KK KK KK IR I A A A A I I A A A A AOA A A I 


startpos = 125; 


len = 4; 

QUSRTVUS ("FSLST QTEMP ", startpos, len, charbin4, 
&error_code) ; 

entrypos = *(int *)charbin4; 


[ORK RK KK KK KK IK A A A A A A A A A A A A I e/ 


/* Get the number of entries in the user space. */ 
[ORK RK KK KK KK I I A A A I I A A A A A A / 


startpos = 133; 
len = 4; 


QUSRTVUS ("FSLST QTEMP ", startpos, len, charbin4, 
&error_code) ; 


numentries = *(int *)charbin4; 


[ORK RK KK KK KK A A A A A A I A A A A A A A A I I e/ 


/* Find the length of the entries. */ 


[ORK RK KK KK KK I A A A A I I A A A A A A A I 


startpos = 137; 


len = 4; 

QUSRTVUS ("FSLST QTEMP ", startpos, len, charbin4, 
&error_code) ; 

entrylen = *(int *)charbin4; 


[ORK RK KK KK KK A A A AA A I I A A A A A A A I I 


/* Loop through the entries and get the names of the file *y. 
/* systems. */ 
[ORK KK RK KK KK KI A A RA A I I RA A A A A  e/ 
for (i=0;i<numentries;++i) 
{ 

startpos = entrypos + 1; 

len = 10; 

QUSRTVUS ("FSLST QTEMP ", startpos, len, FSname, 

&error_code) ; 
[KK RK KK KK KK IK KA A A A I I A A A A A I He / 


/* List the names into the spooled file. i: 
[KK RK KK KK KK KK I A A A I I A A A A AA A ee / 
sprintf (write_string," %.10s <DIR>", FSname) ; 

fprintf (stream, write_string); 

entrypos = entrypos + entrylen; 


} 


else 


{ 
fprintf(stream,"Directory listing for path %.100s\n", name); 
[ORK RK KK KK KK I A A A A I I A A RA A I A I / 


/* Build the attribute selection table for QHFOPNDR. */ 
[ORK RK KK RK KK I I A A A I I A RA A A A I / 
select.fixed.Number_Attributes = 3; 

select.fixed.Offset_First_Attr 16; 

select.offset2 = 28; 

select.offset3 = 40; 

select.att_lenl = 8; 

memcpy (select.att_namel, "QFILSIZE", 8); 

select.att_len2 = 8; 

memcpy (select.att_name2, "QCRIDTIM", 8); 

select.att_len3 = 8; 
memcpy (select.att_name3, "QFILATTR", 8); 
selectionlen = 52; 

memcpy (openinfo, "10 me Oy 


[ORK KK RK KK KA IA AA A A I I A A A A A A I e/ 


/* Find the length of the directory name. * 


[ORK RK KK KK KK IA A A A A A A A A A A A A I He / 
for (i=0;i1<100;i++) 
{ 
if((name[i] == ' ') | | (name[i] == '\x00')) 
break; 
} 


namelen = i; 


[ORK KK KK KK A A A A A A A I A A A A A A A I He / 


/* Open the directory. */ 


[ORK RK KK KK KK A A A A A I I A A A A AA A A I 


QHFOPNDR(dir_handle, name, namelen, openinfo, &select, selectionlen, 
&error_code) ; 


[ORK RK KK KK KK A A A A I I I A A A A A A 


/* Read one entry from the directory. ea 
[ORK KK KK KK KK A A A A I A A A A A A A A I e/ 


QHFRDDR(dir_handle, &buffer, 300, 1, &result_count, &bytes_returned, 


&error_code) ; 


while(result_count > 0) 


{ 


memcpy (attname," ",30); 
memcpy (attval," WO 30,)c9 
att = buffer.attinfo; 

bytes_used = 20; 


[KOK KKK KK KR A I I I I A A A A AA AA A A I A I I / 


/* Loop for the number of attributes in the entry. *Y. 
[KOK KKK IK KK RA I I I I A A A A AA AA AA A A A I I / 


for (i=0;i<buffer.num_att; i++) 


{ 


memcpy (charbin4, att, 4); 
attnamelen = *(int *)charbin4; 
att += 4; 

bytes_used += 4; 

memcpy (charbin4, att, 4); 


attvallen = *(int *)charbin4; 

att += 8; 

bytes_used += 8; 

memcpy (attname, att, attnamelen); 
att += attnamelen; 

bytes_used += attnamelen; 

memcpy (attval, att, attvallen); 
att += attvallen; 

bytes_used += attvallen; 


[BORK KR KK KK KK KKK IA IA I I I I A A A A A A A I 


/* Update att so that its first character is the first ay 
/* character of the next attribute entry. awe 
[KKK KR KK KK KKK KK IR IA A I I I A A A AK A A A I He / 
if ((bytes_used == buffer.offsets[itl]) && 

((it+t1) == buffer.num_att) ) 


att += (buffer.offsets[i] - bytes_used); 


[KOK KR KK KK KKK KR IR IA I I I I A A A A A A I e/ 


/* Tf the attribute is QNAME, then set newname. ay, 
[KOK KKK KR KK KK KR KR AA I I I I A A A A A A a 
if (!memcmp(attname, "QNAME", 5)) 
{ 

memset (newname, ' ', 12); 

memcpy (newname, attval, attvallen); 


[KOR KR KKK KK KKK KK IR IA I I I I A A A A A A A I I He / 


/* Tf the attribute is QFILSIZE, then set filesize. yA 
[KOR KR KR KK KK KR IA IA I I I I A A A A A I I / 
else if(!memcmp(attname, "QFILSIZE", 8)) 
{ 

memcpy (charbin4, attval, 4); 

filesize = *(int *)charbin4; 


} 


[BOK KR KKK KK KKK KK IA IA I I A I A A A A A A A I He / 


/* If it was QCRTDTTM, then set the time. */ 
[BOR KR KKK KK KKK IR IA IA I I I I A A A A A A I I I / 
else if(!memcmp(attname, "QCRIDTTM", 8) ) 

memcpy (&échartime, attval, 13); 
[KOK KK KK KK KKK KR KA IA I I I I A A A A A A I He / 


/* Else the attribute was QFILATTR, so set fileatt. */ 
[KOK KR KK KKK KKK IK IA AA I I I I A A A A A He  / 


else 
memcpy (fileatt, attval, 10); 


[KOK KKK KK KR A I A I I A A A A IA AA AA A A A I I / 


/* If the entry was a directory, list its name and <DIR>. */ 
[KOK KKK KK KR IA I I A I A A A A A AA AA A I I I / 
if (fileatt[3] == '1') 
{ 

sprintf (write_string," %s <DIR>", newname) ; 

fprintf(stream, write_string); 


} 


ett ee ee ee ee ee ee a a a ee a ee Af 


/* If the entry is not a hidden file, list its name and size. */ 
[KOK KK KK KR IR I I A I A A A A A AA AA A A A I I / 
else if (fileatt[1] == '0') 
{ 
sprintf (write_string," %s %d", newname, filesize); 
fprintf(stream, write_string); 


} 


[KOK KK KK KK RR I I A I A A A A AA AA AA A I A I I / 


/* If the entry is not a hidden file or directory, list its */ 


/* date of creation. a 
[KOK KKK KK KR A I A A I A A A A AA AA A A A a I / 
if(fileatt[1] == '0') 


{ 
sprintf (write_string," %.2s-%.2s-%.2s", chartime.month, 
chartime.day, chartime.year); 
fprintf(stream, write_string); 
sprintf (write_string," %.28:%.28s:%.2s\n", chartime.hour, 
chartime.minute, chartime.second) ; 
fprintf(stream, write_string); 


QHFRDDR(dir_handle, &buffer, 200, 1, &result_count, &bytes_returned, 
&error_code) ; 


} /* while */ 

} /* else */ 

[ORK RK KK KK KK I I A A A I A A I A AA A A I 
/* Close the directory. *y 
[ORK RK KK KK KK I A AR A A I I A A A A A A A I e/ 
QHFCLODR(dir_handle, &error_code); 


fclose (stream) ; 


} /* main */ 


Listing Subdirectories 


You should call this program with only one parameter, the parameter that represents the directory you want to list. 


ee ee ee ee ee ee ee a a a aie f 
[OK KK KKK KK KKK I A A A A A A A A A AA A A A I I I / 


/* FUNCTION: List the subdirectories of the path passed to the */ 


/* program to a spooled file. */ 
/* */ 
/* LANGUAGE: ILE C Sl 

a xf 
ie #7 
/* APIs USED: QHFOPNDR, QHFRDDR, QHFCLODR */ 
[* */ 


ie ee ee ee ee ee ee ee ee a ee a ee f 
eee ee ee ee ee ee ee ee a a ee f 


ie ee ee ee ee ee ee ee ee ee a ee fb 


/* INCLUDE FILES */ 
[BORK RK KK KK KK KA A A A A A A RR AA A AA A A a a I / 
#include <stdio.h> 

#include <stdlib.h> 

#include <string.h> 

#include <qhfopndr.h> 

#include <qhfrddr.h> 

#include <qhfclodr.h> 

#include <qusec.h> 


char write_string[100]; 
FILE *stream; 


void print_subdir(char name[100], int numtabs) 


{ 


[OK KK KK KK KK KK IK A A A I A A A A IA A A A A I I I / 


/* Parameters for QHFOPNDR i). 
[ORK RK KKK KK KK I A A A I A A A IA AA AA A I I I / 
char dir_handle[16]; /* Directory handle */ 
int namelen; /* Length of path name ays 
char openinfo[6]; /* Open information */ 


typedef struct { 
Qhf_Attr_Selec_Tbl_t fixed; 
int att_len; 
char att_name [8]; 
} selection_struct; 


selection_struct select; 
int selectionlen; 


ee ee ee ee ee ee ee ee ee ee a ee a ee Af 


/* Error Code Structure *y 
/* */ 
/* This shows how the user can define the variable length iA 
/* portion of error code for the exception data. *y 
Le */ 


[ORK RK KK KKK KK AK A A A A A A A IA A AA A A A ea I / 


typedef struct { 
Qus_EC_t ec_fields; 
char Exception_Data[100]; 
} error_code_t; 


error_code_t error_code; 


[BORK RK KK KK KK KK KA A A A A A A RIA A A A A I I I / 


/* Parameters for QHFRDDR */ 
[ORK RK KK KK KK KK IA IA A A A AR A AA AA AA A A I I I / 
/* The directory handle is the same as for QHFOPNDR */ 


typedef struct { 
Qhf_Data_Buffer_t fixed; 


int num_att; 
int offsets[2]; 
char attinfo[180]; 


} read_buffer; 


read_buffer buffer; 
int result_count; 
int bytes_returned; 


ee ee ee ee a ee ee ee ee a a aie f 


/* Parameters for QHFCLODR ey 
ee ee ee ee ee ee i ee ee a a a aie f 


/* No additional ones need to be declared £7 


[OK KK KK KK KK I A A A A A A A A IA A A A A I I I / 


/* Other declarations */ 
[ORK RK KKK KK KK IK IA A A A A A AR IA A A A A I I / 
char *att; 

char attname [30]; 

char attval[30]; 

int attnamelen; 

int attvallen; 

char newname [30]; 

int newnamelen; 

int filesize; 

char fileatt[10]; 


char tab[5]; 

int bytes_used; 
int Tp WF 

char charbin4 [4]; 
char tempname [100]; 


error_code.ec_fields.Bytes_Provided = 0; 


[ORK RK KK KK KK A I AA A I I A A A A I A A I / 


/* Build the attribute selection table for QHFOPNDR. */ 


[ORK RK KK KK KK I I A A A A I I A A A A A OA A I 


select.fixed.Number_Attributes = 1; 
select.fixed.Offset_First_Attr = 8; 


select.att_len = 8; 

memcpy (select.att_name, "QFILATTR", 8); 
selectionlen = 20; 

memcpy (openinfo, "10 OF 

memcpy (tab," Wp) 


[ORK RK KK KK KK A A AA A A I I A A A A A A A I 


/* Find the length of the directory name. */ 


[ORK RK KK KK KK I A A A A I A A A A A A A A I 
for (i=0;1<100; i++) 
{ 
if((name[i] == ' ') | | (name[i] == '\x00')) 
break; 


} 


namelen = i; 


[ORK RK KK KK KK KR A A AA I I A AR A A A A I 


/* Open the directory. */ 


[ORK KKK KK KK I A A A A A I I A A A A A A A I / 


QHFOPNDR(dir_handle, name, namelen, openinfo, &select, selectionlen, 


&error_code) ; 


[ORK RK KK KK KK I AA A A I I A A RA A A A I / 


/* Read one entry from the directory. #y 
[ORK RK KK KK KK I A A A I I A A A A A A A I / 


QHFRDDR(dir_handle, &buffer, 200, 1, &result_count, &bytes_returned, 


&error_code) ; 


fprintf (stream, "\n") ; 

for (i=0; i<numtabs; i++) 
fprintf(stream, tab); 

fprintf (stream, name) ; 


while(result_count > 0) 

{ 
memcpy (attname," M30) % 
memcpy (attval," M30) 
att = buffer.attinfo; 
bytes_used = 12; 


[KOK KKK KK KK RIA I I A I A A A A AA AA AA A I A I I / 


/* Loop for the number of attributes in the entry. */ 
[KOK KR KKK RR IR I I A I A A A A IAA AA AA A I I I I I / 
for (i=0;i<buffer.num_att; i++) 
{ 

memcpy (charbin4, att, 4); 

attnamelen = *(int *)charbin4; 

att += 4; 

bytes_used += 4; 

memcpy (charbin4, att, 4); 


attvallen = *(int *)charbin4; 

att += 8; 

bytes_used += 8; 

memcpy (attname, att, attnamelen); 
att += attnamelen; 

bytes_used += attnamelen; 

memcpy (attval, att, attvallen); 
att += attvallen; 

bytes_used += attvallen; 


[BOK KKK KK KK KKK IR IA IA A A I I A A A A A A I I I / 


/* Update att so that its first character is the first */ 
/* character of the next attribute entry. ef 
[KOK KK KKK KK KK KR IA IA I I I I A A A A A A a I / 
if ((bytes_used == buffer.offsets[itl]) && 

((it+t1) == buffer.num_att) ) 


att += (buffer.offsets[i] - bytes_used); 


[BOK KR KK KK KKK KK IA IA I A I I A A A A A A A He I 


/* Tf the attribute is QNAME, then set newname and ay 
/* newnamelen just in case the entry is a directory. aye 
[KKK KR KKK KK KK KR IA IA I A I I A A A A A A I 
if (!memcmp(attname, "QNAME", 5)) 
{ 

memcpy (newname, attval, attvallen); 

newnamelen = attvallen; 


} 


[KOK KR KK KK KKK IR IA IA A I I I A A A A A / 


/* Else the attribute was QFILATTR, so set fileatt. */ 
[KOK KR KK KK KK KK IR IA I I I I A A A A A A a I / 
else 
memcpy (fileatt, attval, 10); 
} 


[KOK KK KK RK RR I A A I A A A A IAA AA AA A I I I I / 


/* If the entry was a directory, construct new path name and */ 
/* print_subdir to print the subdirectory. */ 
[KOK KKK HK KK RR A I A I A AA A AA AA AA A A A a I / 
if (fileatt[3] == '1') 
{ 

memcpy (tempname, name, 100); 

strcat (name, "/"); 

strcat (name, newname) ; 

memcpy (newname, name, namelen + newnamelen + 1); 

print_subdir(newname, numtabs + 1); 

memcpy (name, tempname, 100); 


} 


QHFRDDR(dir_handle, &buffer, 200, 1, &result_count, &bytes_returned, 
&error_code) ; 


} /* while */ 


[ORK RK KK KK KK I A A A I I A A A A A A a  e/ 


/* Close the directory. af: 


[ORK RK KK KK RK KK I A A A A I A A A A A OA A A A I 


QHFCLODR(dir_handle, &error_code); 


}/* print_subdir */ 


main(int argc, char *argv[]) 
{ 


char dir_name[100]; 


[ORK RK KK KK KK I A A A A A A I A A A A A A 


/* Make sure we received the correct number of parameters. The */ 


/* argc parameter will contain the number of parameters that ¥y, 
/* was passed to this program. This number also includes the */ 
/* program itself, so we need to evaluate argc-l. */ 


[ORK RK KK KK IR A A A I A I A A A AA A A I 


if (((arge - 1) <1) || ((arge - 1 > 1))) 

[ORK RK KK KK KK I A A I I I A A A A AA A A 
/* We did not receive all of the required parameters, or */ 
/* received too many. Exit from the program. *y 


[ORK RK KK KK KK KK A AA A A I A A A A AOA A A I He / 
exit (1); 


[ORK RK KK KK KK A A A A A A A A A A A A A A A I / 


/* Open QPRINT file so that data can be written to it. If the */ 


/* file cannot be opened, print a message and exit. */ 
[ORK RK KK KK KK I I A A A I A A A A A A A A I He / 
if((stream = fopen("QPRINT", "wb")) == NULL) 


{ 
printf("File could not be opened\n"); 


exit(1); 
} 
memset (dir_name, ' ', 100); 
memcpy (dir_name, argv[1l], 100); 
if (!memcmp(dir_name, " ", 1)) 


{ 


fprintf(stream,"No directory specified"); 


} 


else 


{ 
fprintf(stream,"Directory substructure starting at %.100s", dir_name); 
print_subdir(dir_name, 0); 


} 


fclose (stream) ; 


} /* main */ 


Saving to Multiple Devices 


The following example program shows how to save a large library using more than one device at the same time. 


[KKK KK KK KKK IK IA IA A A I A A AA AA IA IA A A I A I I I 


/* PROGRAM: SaveBigLib ef 
/* */ 
/* LANGUAGE: ILE C for OS/400 *Y, 
7s */ 
/* DESCRIPTION: This is an example program for the use of */ 
/* a media definition in a save operation. */ 


/* It saves library BIGLIB in parallel format to * 


/* two media files, using tape media library */ 


/* TAPMLBO1. */ 
ha * 
/* The flow of this program is as follows: */ 
/* (1) Build media definition input. * 
pa (2) Create a media definition using */ 
aa QsrCreateMediaDefinition. */ 
/* (3) Save library BIGLIB using the media */ 
/* definition. */ 
ba ears 
/* APIs USED: QsrCreateMediaDefinition, QCMDEXC */ 
/* */ 


[BKK RK KK KKK KKK I IA A A A RA AA IA AA A A I A I I He / 


#include <qcmdexc.h> 
#include <qsrlib01.h> 
#include <qusec.h> 
#include <string.h> 


[KK RK KK KKK KKK IK AA IA A A A A IA IA IA A I A A I I / 


/* Variables for QsrCreateMediaDefinition */ 
[KK RK KK KK KKK IK IR AA IA A A A A IA IA AA A A A I I He / 
char Data_Buffer [1000]; 

Qsr_TAPE0100_t *Tnput_Data; 

Qsr_TAPE0100_Device_t *Device; 

Qsr_TAPE0100_File_t *Media_File; 

char *Next_Free; 

char *Volid; 

Qus_EC_t Err_Code; 

int Data_Length; 

char Text [50]; 


[KK RK KK KK KKK KR AA AA A A A RA AIA AA A I A A I I / 


/* Variables for QCMDEXC ard 
[ORK RK KK KKK KK I AK AA IA A RR A AA AA IA A A I A I He / 
char Cmd_String[100]; 


decimal(15,5) Cmd_Length; 


[ORK RK KK KKK KK KK A IA IA A RA AIA A A I A I A I I 


/* Start of main() * / 


[KK RK KK KKK KK AK AA IA A A AR AA AA A A A A I A I I I 


int main (int argc, char *argv[]) { 


[KK RK KKK KK KK I A IA IA A A A A IA A AA IA A I A I I / 


/* Specify input data for QsrCreateMediaDefinition. */ 
[KK RK KK KKK KKK IK AR IA A A I RR AA IA IA A A I A I A I I / 
fag */ 
/* Build general media definition input data. */ 
/* Use one device with two parallel device resources. *f 
/* */ 


memset (Data_Buffer,0,sizeof (Data_Buffer) ); 
Input_Data = (Qsr_TAPE0100_t*)Data_Buffer; 
Next_Free = (char*) (Input_Data + 1); 


Input_Data->Maximum_Resources = 2; 

Input_Data->Minimum_Resources = 2; 

Input_Data->Offset_First_Device = Next_Free - Data_Buffer; 
Input_Data->Device_Count = 1; 

hs ey 
/* Build input data for the first device. aire 
/* Use device TAPMLBO1 with two media files. *f 
Es A 
Device = (Qsr_TAPE0100_Device_t*) Next_Free; 


Next_Free = (char*) (Device + 1); 
memcpy (Device->Device_Name,"TAPMLBO1 ",10); 
Device->Offset_First_File = Next_Free - Data_Buffer; 


Device->File Count = 2; 


fr */ 
/* Build input data for the first media file for device TAPMLBO1. */ 
/* Use the default sequence number, and volumes VOL11 and VOL12. */ 


is ol A 
Media_File = (Qsr_TAPE0100_File t*)Next_Free; 


Next_Free = (char*) (Media_File + 1); 
Media_File->Sequence_Number = 0; 
Media_File->Offset_First_Volume_Id = Next_Free - Data_Buffer; 


Media_File->Volume_Id_Count = 2; 
Media_File->Volume_Id_Length = 6; 
Media_File->Starting_Volume = 1; 


Data_Length = Media_File->Volume_Id_Count 

* Media_File->Volume_Id_Length; 
Volid = Next_Free; 
memcpy (Volid,"VOL11 VOL12 ",Data_Length) ; 


if (Data_Length % 4) /* Ensure that Next_Free */ 
Data_Length += (4 - (Data_Length % 4)); /* is incremented by a */ 
Next_Free += Data_Length; /* multiple of 4. * / 


Media_File->Offset_Next_File = Next_Free - Data_Buffer; 


Pe mh 
/* Build input data for the second media file for device TAPMLBO1. */ 
/* Use the default sequence number, and volumes VOL21 and VOL22. */ 
/* */ 
Media_File = (Qsr_TAPE0100_File t*)Next_Free; 


Next_Free = (char*) (Media_File + 1); 
Media_File->Sequence_Number = 0; 
Media_File->Offset_First_Volume_Id = Next_Free - Data_Buffer; 


Media_File->Volume_Id_Count = 2; 
Media_File->Volume_Id_Length = 6; 
Media_File->Starting_Volume = 1; 


Data_Length = Media_File->Volume_Id_Count 

* Media_File->Volume_Id_Length; 
Volid = Next_Free; 
memcpy (Volid,"VOL21 VOL22 ",Data_Length) ; 


if (Data_Length % 4) /* Ensure that Next_Free */ 
Data_Length += (4 - (Data_Length % 4)); /* is incremented by a */ 
Next_Free += Data_Length; /* multiple of 4. * / 


[OK KK KK KK KKK KK IA AA AA A A A AAA AA A A I Ie A / 


/* Create the media definition. */ 
[OK KK KR KK KK KK IK AA IA IA I AA AAA AA A A A I A / 
Data_Length = Next_Free - Data_Buffer; 

memset (Text, ' ',sizeof(Text)); 

memcpy (Text, "Save BIGLIB",11); 

QsrCreateMediaDefinition ( 


"SAVEBIGLIBOTEMP ", /* Media definition * / 

name, library */, 
Data_Buffer, /* Input data */ 
Data_Length, /* Length of data aw A 
"TAPE0100", /* Format name as 
"*USE Mw, /* Public authority */ 
Text, /* Text description */ 
‘yy /* Replace if it exists */ 
&Err_Code) ; /* Error code */ 


[KK RK KR KKK KK KKK IA AA IA IA I I I AAA AAA AA IA A a I I / 


/* Save library BIGLIB using the media definition. */ 
[OK KK KK KK KK KK A IA AA IA I A AAA A AA A A a I I / 
strcpy (Cmd_String, 

"SAVLIB LIB(BIGLIB) DEV( 
Cmd_Length = strlen(Cmd_String) 
QCMDEXC (Cmd_String,Cmd_Length) ; 


*MEDDFN) MEDDFN(QTEMP/SAVEBIGLIB) ") ; 


Lf 


return 0; 


Scanning String Patterns 


A typical use of the QCLSCAN API is to allow the work station user to retrieve all records that contain a specified pattern. 


Example 1 
Assume a 20-character database field containing only uppercase characters and the pattern 'ABC’ is scanned for. The user program 
calls the QCLSCAN API for each database record read. The parameters would be as follows: 

Field Name _ Result 

STRING The 20-byte field to be scanned 

STRLEN 20 


STRPOS 1 
PATTERN ‘ABC’ 
PATLEN 3 
TRANSLATE '0' 
TRIM ‘0 
WILD > 


RESULT A value returned to your program 


The following describes some fields and the results of the scan: 


Scan String Result Comments 

1 ABCDEFGHIJKLMNOPORST 001 

2 XXXXABCXXXXXXXXXXXXX 005 

3 abcXXXXXXXXXXXXXXXXX 000 Translation not requested 

4 XXXABCXXXXXABCXXXXXX 004 First occurrence found; see note 
5 ABABABABBCACCBACBABA 000 Not found 

6 ABABABCABCABCABCABCA 005 


Note: In scan 4, the string has two places where the pattern could have been found. Since the STRPOS value is 1, the first value 
(position 004) was found. If the value of STRPOS had been 4, the result would still have been 004. If the STRPOS value had been in 
a range of 5 through 12, the result would have been 012. 


Example 2 


Assume a 25-character database field containing only uppercase characters and a user program that will prompt for the pattern to be 
scanned, which will not exceed 10 characters. The work station user is allowed to enter | through 10 characters to search with and 
trailing blanks will be trimmed from the pattern. The program would call the QCLSCAN program for each database record read. The 
program parameters would be as follows: 


Field Name _ Result 

STRING The 25-byte field to be scanned 
STRLEN 29 

STRPOS 1 

PATTERN _ Varies 

PATLEN 10 

TRANSLATE '0' 

TRIM T 


WILD m 


RESULT A value returned to your program 


The following describes some fields and the results of the scan: 


Scan String 

1 ABCDEFGHIJKLMNOPORS TUVWXY 
ABCDEFGHIJKLMNOPORS TUVWXY 
ABCDEFGHIJKLMNOPORS TUVWXY 
XXXXABCXXXXXXXXXXXXXXXXXX 
abcXXXXXXXXXXXXXXXXXXXXXX 
ABCXXXXXABC EXXXXXXXXXXXX 
XXXABCXXXXXABCXXXXXXXXXXX 


HWA UB WD 


Pattern 
"CDE 
'CDEFGH 


'CDEFGHIJKL 


"ABCD 
"ABC 
"ABC E 
"ABC 


Result 
003 
003 
003 
000 
000 
009 
004 


Comments 


Not found 
Not translated 


See note 


Note: In scan 7, the string has two places where the pattern could be found. Since the STRPOS value is 1, only the first value 
(position 004) is found. If the value of STRPOS were 4, the result would still be 004. If the STRPOS value were in the range of 5 


through 12, the result would be 012. 


Example 3 


Assume a 25-character database field containing either uppercase or lowercase characters. The user program prompts for the pattern 
to be scanned, which does not exceed 5 characters. The work station user can enter 1 through 5 characters to be found. The system 
trims trailing blanks from the pattern. If the user enters an asterisk (*) in the pattern, the asterisk is handled as a wild character. The 
program calls the QCLSCAN program for each database record read. The parameters are as follows: 


Field Name_ Result 


STRING The 25-byte field to be scanned 
STRLEN 25 

STRPOS 1 

PATTERN _ Varies 

PATLEN 5 

TRANSLATE '\' (See note 1) 

TRIM ‘T 

WILD ue 

RESULT A value returned to your program 


The following describes some fields and the results of the scan: 


Scan String 
1 ABCDEFGHIJK 
ABCDEFGHIJK 


LMNOPORS TUVWXY 
2 LMNOPORS TUVWXY 
3 abcdefghijklmnopqrstuvwxy 
4 abcdefghijklmnopqrstuvwxy 
5 abcXXXXXXXXXXXXXXXXXXXXXX 
6 
7 
8 


XXXAbcXXXXXabcXXXXXXXXXXX 
ABCDEFGHIJK 
ABCDEFGHIJK 


LMNOPORSTUVWXY 
LMNOPORS TUVWXY 


Pattern 
"CDE 
'"C*E 
"CHKKG 
"ABCD 
'C*E 
"ABC 
"*BC 


Result 
003 
003 
003 
001 
000 
004 

-003 

-004 


Comments 


See note 1 
Not 
See 
See 
See 


found 
note 2 
note 3 
note 4 


1. When field translation is specified (the TRANSLATE parameter is specified as '1'), the string is translated to uppercase 
characters before scanning occurs; the data in the string is not changed. 


2. In scan 6, the string has two places where the pattern could have been found. Since the STRPOS value is 1, the first value 


(position 004) was found. 


3. In scan 7, the wild character (*) is the first character in the trimmed pattern. Wild characters cannot be the first character in a 


pattern. 


4. In scan 8, the trimmed pattern is blank. 


Using COBOL Program to Call APlis 


This example COBOL program uses the example error handler in Error Handler for Example COBOL Program. 


Note: In order for this example to run successfully, the error program, ACERRF24 (shown in Error Handler for Example COBOL 
Program), must exist in a library called UTCBL. 


IDENTIFICATION DIVISION. 
PROGRAM-ID. ACF24. 


KR KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KK KKKKKKK 
KR KKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KK KKKK KKK KKKKKK 
* 


FUNCTION: SHOWS HOW TO CALL THE VARIOUS APIs, WHILE 
TESTING THAT THEY WORK PROPERLY. 


LANGUAGE: COBOL FOR OS/400 


* 
* 
* 
* 
* 
* 


APIs USED: QLRRTVCE, QLRCHGCM, QLRSETCE 


* 
KK KKK KKK KKK KKK KK KKK KKK KKK KEK KKK KKK KKK KKK KEK KKK KKK KKK KKK KKK KKKKKK 
KR KKK KKK KKK KKK KK KKK KKK KKK KEK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKKKK KEK 


ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. IBM-AS400. 
OBJECT-COMPUTER. IBM-AS400. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 


01 old. 
05 oldname PIC X(10). 
05 oldlibr PIC X(10). 

77 scope PIC X VALUE "P", 

O01 errparm. 
05 input-l PIC S9(6) BINARY VALUE ZERO. 
05 output-1 PIC S9(6) BINARY VALUE ZERO. 
05 exception-id PIC X(7) 
05 reserved PIC X(1). 
05 exception-data PIC X(50). 

Ol new. 
05 newname PIC X(10) VALUE "ACERRF24", 
05 newlibr PIC X(10) VALUE "UTCBL". 

77 newlib PIC X(10). 


PROCEDURE DIVISION. 

main-proc. 
DISPLAY "in ACF24"., 
PERFORM variation-01 THRU end-variation. 
STOP RUN. 


variation-0Ol. 
KK KKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KEK KKK KKK KKK KKK KKK KKK KKKK KK 


* * 
* This variation addresses the situation where there is no * 
* pending COBOL main, so no pending error handler can exist. * 
* * 


KR KKK KKK KKK KKK KKK KEK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KK KKK K KK KKKKKKEK 


DISPLAY "no pending so expect nothing but error LBE7052". 
MOVE SPACES TO old exception-id. 
KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KK KKKKKKKKKKKKKKKKKKKAKKKKK 
* By setting error parm > 8, expect escape message oy 
* LBE7052 to be returned in error parameter. * 
KKK KK KKKKK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKKKKKKKKKKKKKKKKKAKKKKK 
MOVE LENGTH OF errparm TO input-l. 
CALL "QLRRTVCE" USING old scope errparm. 


IF exception-id IS NOT = "LBE7052" THEN 


DISPLAY "** error -— expected LBE7052" 
ELSE 

DISPLAY "LBE7052 was found" 
END-IF. 


KR KKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KK KK KKKK KK KKK KK KK 


* Reset input-1 to ZERO, thus any further errors will cause * 
* COBOL program to stop. * 
KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK 
MOVE O TO input-l. 
MOVE SPACES TO old exception-id. 


variation-02. 
KK KKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKKKKK 


* * 
* This variation creates a pending run unit. It then makes * 
* sure that no pending error handler has been set. os 
* * 


KR KKK KKK KKK KKK KK KKK KKK KKK KK KKK KK KKK KKK KKK KKK KKK KK KKKK KKK KKKK KK 


DISPLAY "create pending run unit". 
CALL "QLRCHGCM" USING errparm. 


KK KKK KKK KKK KKK KK KKK KKK KKK KEK KKK KKK KKK KKK KKK KKK KK KK KKKK KKK KKKK KK 


* * 
* No pending error handler exists so *NONE should be * 
* returned. . 
* * 


KK KKK KKK KKK KKK KK KKK KKK KKK KEK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KK KK 


CALL "QLRRTVCE" USING old scope errparm. 
DISPLAY "Retrieved Error Handler is=" old. 


IF oldname IS NOT = "*NONE" THEN 
DISPLAY "** error -— expected *NONE for error handler" 
END-IF. 


MOVE 0 TO input-l. 
MOVE SPACES TO old exception-id. 


variation-0O3. 
KKK KK KKK KKK KKK KK KKK KKK KKK KEK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKKKKK 


This variation sets an error handler for the pending 
run unit and then does another check to make sure it 


* * 
* * 
* * 
* was really set. a 
* * 
KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK KK KKK K 


CALL "QLRSETCE" USING new scope newlib old errparm. 


IF oldname IS NOT = "*NONE" 

DISPLAY "** error in oldname " 

END-IF. 

IF newlib IS NOT = "UTCBL" 

DISPLAY "** error in new library " 

END-IF. 
KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK 
* Call the retrieve API to check to make sure that the i 
* set API worked. * 


KKK KK KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKKKK KKK KKK KKKKKKKKKKKKKKK 
MOVE SPACES TO old exception-id. 
CALL "QLRRTVCE" USING old scope errparm. 
DISPLAY "Retrieved Error Handler is=" old. 


IF oldname IS NOT = "ACERRF24" OR oldlibr IS NOT = "UTCBL" 
DISPLAY "** error - expected ACERRF24 error handler" 
END-IF. 


end-variation. 


Error Handler for Example COBOL Program 


This example error handler works with Using COBOL Program to Call APIs. 


IDENTIFICATION DIVISION. 
PROGRAM-ID. ACERRF24. 


KK KKK KKK KKK KKK KK KKK KKK KKK KEK KKK KKK KKK KK KKK KKK KKK KK KKKKKKKKKKK KEK 


KR KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KK KK KKK KKKKKKKKKK 


* FUNCTION: Error handler for preceding example COBOL program 
* 
* LANGUAGE: COBOL FOR OS/400 
* 
* 


APIs USED: None 


KR KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KK KK KKK KKKKKKKKKK 


KKK KKK KK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KKK KK KKK KKK KK KKKKKKKKKKKEKK 


ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. IBM-AS400. 
OBJECT-COMPUTER. IBM-AS400. 
SPECIAL-NAMES. SYSTEM-CONSOLE IS SYSCON. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
77 scope PIC X VALUE "P". 
01 errparm. 
05 FILLER PIC X(30). 
LINKAGE SECTION. 
77 cobol-id PIC X(7). 
77 valid-responses PIC X(6). 
O01 progr. 
05 progname PIC X(10). 
05 proglibr PIC X(10). 
77 system-id PIC X(7). 
77 len-text PIC S9(9) COMP-4. 
O01 subtext. 
03 subchars PIC X OCCURS 1 TO 230 TIMES 
DEPENDING ON len-text. 
77  retcode PIC X(1). 
PROCEDURE DIVISION USING cobol-id, valid-responses, 
progr, system-id, subtext, len-text, retcode. 


main-proc. 
KKEKKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKKKEK 


* check for typical messages and take appropriate action * 
KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKKKK KKK KKK KKKEKKKKKKKKKKKKKKKK 
EVALUATE cobol-id 
WHEN "LBE7604" 


KKK KKK KK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KKK KKK KK KK KKK KKK KKK 


* stop literal, let the user see the message a 
KKK KKK KKK KK KKK KKK KK KKK KKK KEK KKK KKK KKK KEK KKKKKKKKKKKKKKKKK KKK 
MOVE SPACE TO retcode 
WHEN "LBE7208" 


KR KKK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KKK KK KEK 


* accept/display, recoverable problem answer G to continue 
KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKKKK KKK KKK KKKKKKKKKKKKKKKKKKK 
MOVE "G" TO retcode 
WHEN OTHER 
KKK KKK KKK KKK KK KK KKK KKK KKK KKK KKKKK KKK KEK KKKKKKKKKKKKKKKKKKKK 
* for all other messages signal system operator and * 
* end the current run unit ss 
KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKKKKKKKKEKKKKKKKKKKKKKKKKKKKKK 
DISPLAY "COBOL Error Handler ACERRF24 " 
"Found message " cobol-id 
" Issued from program " progr 
UPON syscon 
DISPLAY " Ended current run unit" 


UPON syscon 
MOVE "C" TO retcode 
END-EVALUATE. 
GOBACK. 


Using the User-Defined Communications Programs for File 
Transfer 


This section provides a simple example showing how X.25-oriented applications use the user-defined communications support to 
connect to remote systems. Two user-defined application programs written in the ILE C programming language are used to illustrate 
a simple file transfer between two systems over an X.25 packet-switching data network (PSDN). Although an X.25 example is 
shown, many of the same concepts can be applied to applications running over token-ring and Ethernet local area networks (LANs). 
For the purposes of the examples, the APIs are referred to by their call names. The includes header, hexconv, and typedefs are not in 
QSYSINC. These includes are only documented in the examples. 


For this example, the following network configuration will be used. 


System A 


Source 
Application 


User-Defined 
Communications 
Support 


System B 


Target 
Application 


User-Defined 
Communications 
Support 


TREE EERESE 


X.25 Overview 


In this example X.25 network, the source application on System A is responsible for establishing a switched virtual circuit, or 
connection to the target application running on System B. This is done by using the remote network address (System B's address) of 
X'0000652'. When the target application on System B is initialized, it waits for notification of an incoming call packet before 
proceeding. Once the virtual circuit is established, the source application reads records from a file into its output buffer and sends 
them to the target application using normal X.25 data transfer procedures. While receiving the file data, the target application writes 
the data to a local file on System B. When the file transfer completes, the source application closes the connection by issuing an X.25 
clear request packet and ends. When receiving the clear indication packet, the target application also ends. 


User-Defined Communications Support Overview 


Both the source and target applications call the Query Line Description (QOLQLIND) API to obtain information about the local X.25 
line being used. This information is stored in a local control block for use in establishing the peer connection during X.25 connection 
processing. Both applications also call the Enable Link (QOLELINK) API to enable the link for future communications. The iSeries 
server line name, communications handle, and remote DTE address are passed to both programs as arguments to the C function 
main(). For simplicity, the user space names and data queue name on the call to the QOLELINK API are coded directly in the 


applications. 


Note: Keyed data queue support is used by both applications. The key length is 3 and the keys used are source (SRC) and target 
(TGT) for the source and target applications, respectively. 


Activating Filters 


Once the links have been enabled and both applications have read their respective enable-complete entries from their data queues, the 
target application program calls the Set Filter (QOLSETF) API to activate a filter. The filter activated then identifies the protocol of 
the local X.25 service user. This filter is used by the user-defined communications support on System B to route incoming calls. The 
actual filter type activated is X'00' (for X.25 PID) and its associated value is X'21'. For more information concerning filters, see . 
After activating the X'21' filter, the target application waits for the source application to request a connection. 


Establishing a Connection 


The source application calls the Send Data (QOLSEND) API with a X'B000' operation in its output data buffer to establish a 
switched virtual circuit (SVC) to the target application. Included in the first byte of the call user data is the protocol ID of the target 
application, or X'21'. When the user-defined communications support on System B sees the incoming call packet with the first byte of 
user data equal to a previously activated filter, the call is routed to the process responsible for activating that filter. In this case, the 
target application will receive notification of an incoming call since it previously activated filter X'21'. 


While waiting for the incoming call, the target application calls the Receive Data (QOLRECV) API to receive a X'B201' operation 
with incoming call data. After doing so, the target application accepts the X.25 connection by calling the QOLSEND API with a 
X'B400' operation in its output data buffer. See for more information. 


Sending Data 


Once the peer connection is established between the source and target applications running on System A and System B respectively, 
the file transfer takes place. The source application reads records from a local file and calls the QOLSEND API with X'0000' 
operations in its output data buffer to transfer the file data to System B. This process continues until the entire contents of the source 
file has been sent to System B. 


Receiving Data 


After accepting the X.25 connection, the target application waits until its data queue receives incoming-data entries. When the first 
entry is read from the queue, the QOLRECV API is called to determine which operation was received. Barring failure, the target 
application should receive a X'0001' operation as a result of the QOLRECV API call. The data contained in the input data buffer is 
the file data received from System A. While receiving the file data, the target application writes the data to a local file. This process 
continues until the entire contents of the file is received from System A. The target application then assumes the file transfer is 
complete when an operation other than a X'0001' operation is received after a successful call to the QOLRECV API. Most likely, the 
first non-X'0001' operation received will be X'B301' operation, signalling that the user-defined communications support running on 
System B received an SVC clear indication. 


Clearing the Connection and Disabling Links 


Once the entire contents of the file has been read and sent to System B, the source application calls the QOLSEND API with a 
X'B100' operation in its output data buffer to clear the X.25 connection. Afterwards, the source application closes its local file, 
disables its local link by calling the QOLDLINK API, and ends. 


When the source application program sends a X'B100' operation, it causes the target application to receive a X'B301' operation. After 
receiving this operation, the target application program calls the QOLSEND API with a X'B 100' operation to locally close the 
connection between itself and the user-defined communications support. Afterwards, the target application closes its local file, 
disables its local link by calling the QOLDLINK API, and ends. 


Using Timers and the Data Queue Support 


Both the source and target application programs use the user-defined communications support timer service to manage the reception 
of certain operations. This is done by setting a timer before checking the data queue for an entry. For example, the target application 
sets a timer to manage the reception of file data from the source application. If the timer expires, the user-defined communications 
support places a timer-expired entry on the application's data queue. The target application then assumes when receiving this entry 
that the source application ended abnormally. The target application can then take the appropriate action to end itself. 


ILE C Compiler Listings 


Below are the listings for the source and target applications described in the previous paragraphs. Note the reference numbers (for 
example, (1)) in the listings. Detailed explanations of each reference number block are found in Source application program listing 


references and Target application program listing references. 


The target application compiler listing can be found in Target Application on System B Listing. 


Source Application on System A Listing 


In this example, the source application is the initiator of all meaningful work. In summary, the source program listed on the following 
pages does the following: 


e Calls the QOLQLIND API to get local X.25 line information 


Opens the local file 


Calls the QOLELINK API to establish a link for communications 


Calls the QOLSEND API with X'B000' operation to establish a peer (SVC) connection 


e Sends the local file to the target system using X'0000' operations 


Calls the QOLSEND API with X'B100' operation to clear the peer (SVC) connection 


Calls the QOLDLINK API to disable the link 


@ Calls the QOLTIMER API to manage the reception of data queue entries 


To create the program using ILE C, use the Create Bound C (CRTBNDC) command. 


Program name ...... . . . : (SOURCE) 
Library name dee oy Ow. 8 UDCS_APPLS 
Source file. s # 2 woe woe a « 4 QCSRC 
Library name ........ 3 UDCS_APPLS 
Source member name ......: SOURCE 
Text Description .......: Source Application Example 
OQULDUE «wo koe oe me HO Se ew FE *NONE 
Compiler options : *SOURCE *NOXREF *SHOWUSR 
*SHOWSYS *NOSHOWSKP *NOEXPMAC 
*NOAGR *NOPPONLY *NODEBUG 
*GEN *NOSECLVL *PRINT *LOGMSG 
*USRINCPATH 
Checkout Options *NOAGR 
Optimization *NONE 
Inline Options: 
Inliner *OFF 
Mode *NOAUTO 
Threshold 250 
Limit é 2000 
Debugging View *NONE 
Define Names foe eS Hoe aad *NONE 
Language Level ........: * SOURCE 
Source Margins: 
L@ft. margin « . « « “2% « « ~. & 1 
Right margin ........: 32754 
Sequence columns: 
Left column . «© 2 « « © @ «© « 2 *NONE 
Right column ........: 
Message flagging level ....: 0 
Compiler messages: 
Message limit ........: *NOMAX 
Message limit severity ...: 30 


Replace Program Object ....: *YES 


User Profile 
Authority 
Target Release 
System includes 


*USER 
*LIBCRTAUT 
*CURRENT 
*YES 


[KK RK KK KK KK KK IK IA IA A A AR A AA IA A A I A I A I I He / 


[** 
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Program Name 


Function: 


: Source Application Program Example 


This is the source application program example that uses 
X.25 services provided by the user-defined communications 
support to transfer a simple file to the target application 
program running on system B. 


following: 


This program performs the 


O01. Open the source file name INFILE. 
02. Call QOLQLIND API to obtain local line information. 
03. Enable a link. 
a 'BOOO'X operation (call request). 


04. Send 


05. Receive a 


06. Read 
send 


"BOO1'X operation 


(call confirmation). 


record(s) from the file opened in step 1). and 


'0001'X operation(s) 


the target application program. 


O07. Send 


08. Receive a 


a 'B100'X operation 
'B101'X operation. 


09. Disable the link enabled in step 3). 


to transfer the file to 


(clear call request). 


A data queue will be actively used to manage the operation 


of this program. 


Data queue support will be used to monitor 


for the completion of the enable and disable routines, as 


well as timer expirations and incoming data. 


Timers are 


used to ensure that there will never be an infinite wait on 


the data queue. 


If a timer expires, 


be disabled and the program will stop. 


Inputs: 


the link enabled will 


The program expects the following input parameters 


Line Name 


CommHandle: 


Remote DTE Address: 


Outputs: 


: This is the name of the line description 


to identify the link enabled. 


of System B. 


that will be used to call the QOLELINK API. 
The line must be an X.25 line with at least 
one SVC of type *SVCBOTH or *SVCOUT. 


This is the logical name that will be used 


The is the Local Network Address 


Current status of the file transfer will be provided when 


running this program. 


and the program will end. 


successfully, 
posted. 


Language: ILE C for OS/400 


APIs used: QO] 


LELINK, QUSPTRUS, 


QO!l 


LTIMER, QRCVDTAQ 


If an error should occur, 
message will be displayed indicating where the error occurred 


then a 


If the program completes 
a "successful completion" message will be 


QOLRECV, QOLSEND, 


QOLDLINK, 


x* / 
xx / 
** / 
xx / 
x* / 
xx / 
xx / 
xx / 
xx / 
xx / 
xx / 
x* / 
xx / 
xx / 
xx / 
xx / 
xx / 
xx / 
xx / 
xx / 
x* / 
xx / 
xx / 
xx / 
xx / 
xx / 
xx / 
xx / 
xx / 
x* / 
xx / 
xx / 
xx / 
xx / 
xx / 
xx / 
xx / 
xx / 
x* / 
*x* / 
xx / 
x* / 
xx / 
xx / 
xx / 
x* / 
xx / 
xx / 
xx / 
x * / 
xx / 
x* / 
xx / 
xx / 
xx / 
xx / 


[KK RK KKK KK KKK KK IA IA A A RR A IA IA A A I A A I I / 


[BKK RK KKK KK KK I IA IA A A A I A AA AA A A A A I A I I / 


[KK RK KK KK KK KK KKK AA IA A A A A A AA IA A A I A I A I I / 


#include "header" 


#include 


"typedef" 


#include "hexconv" 


(1) 

[KKK KK KK KKK KK Typedef Declarations TKK KK KK KK / 

(2) 

void senddata(sendparms *a, char *b, desc *c, char *d, char *e, int f); 
void sndformatl(sendparms *a,char *b, char *c, char *d, qlindparms *f); 
void sndformat2 (sendparms *a, char *b, char *c); 

void setfilters (hdrparms *a); 

void byte (char *a, int b, char *c, int d); 

void printespec (espec *a); 

void settimer(unsigned short *a,char *b,qentry *c,usrspace *d,char *e); 
void dequeue (int a, char *b, gentry *c, usrspace *d); 

void x25lind (qlindparms *a, char *b); 


int getline (char *a, int b, FILE *c); 


void 
void 


void 


disablelink (disableparms *a, char *b, usrspace *c)j; 
handler (disableparms a, usrspace *b); 


_GetExcData(_INTRPT_Hndlr_Parms_T *parms) ; 


[ORK RK KKK KK KK KK A A A AR A A RA A A A  / 


[BKK KK KK KKK KK KKK Start Main Program TK KK / 
[OK KK KK KKK KK I A A IR A A RA A OA Oe  / 


main (int argc, char *argv[]) 
ee reeren Variable Declarations TK A eK KK KK KK / 
usrspace inbuff, /* Input Data Buffer */ 
indesc, /* Input Buffer Descriptor */ 
outbuff, /* Output Data Buffer */ 
outdesc, /* Output Buffer Descriptor */ 
qname; /* Data Queue */ 
int length, /* Data Queue key length */ 
linesiz, /* Length of line that is read in */ 
i= 0; /* counter */ 
unsigned short expctid; /* Message ID that is expected */ 
char commhandle[10], /* Command Line Parameter */ 
*buffer, /* Pointer to buffer */ 
rmtdte[18], /* Remote DTE read in */ 
line[132], /* Line to read in * fe 
key[256]; /* Data Queue key identifier */ 
desc *descriptor; /* Pointer to buffer descriptor */ 


/** definitions for the API functions **/ 
enableparms enable; 

disableparms disable; 

sendparms send; 

recvparms recv; 

setfparms setf; 

timerparms timer; 

qlindparms qlind; 

gentry dataq; 

hdrparms *header; 


(3) 

/***---— Open the file to send to remote side ee AS 

if ((fptr = fopen("UDCS_APPLS/INFILE(INFILE)", "r")) == NULL) 
{ 
printf ("Unable to open source input file in UDCS_APPLS LIB.\n"); 
printf ("The Program was terminated.\n\n"); 
return; 
} 

/***--- Open the display file as our input screen. ----**/ 

if ((screen = fopen("ERRORSPEC", "ab+ type=record")) == NULL) 


{ 

printf ("Unable to open display file.\n"); 
printf ("The Program was terminated.\n\n"); 
return; 


} 


/** set the exception handler **/ 


signal (SIGALL,SIG_DFL); 
/**x Clear the command line Parameters **/ 


strncpy (enable.linename, " ", 10); #/* Clear linename */ 
strncpy(commhandle, " We S10) 55 /* Clear Commhandle*/ 
strncpy(rmtdte, " Wie Lh) ef /* Clear Remote DTE*/ 
/** Receive command line Parameters **/ 

strncpy (enable.linename, argv[1], strlen(argv[1])); 
strncpy(commhandle, argv[2], strlen(argv[2])); 

strncpy(rmtdte, argv[3], strlen(argv[3])); 

rmtdte[strlen(argv[3])] = '\0'; 

/** Initialize the user spaces **/ 

strncpy (inbuff.library, "UDCS_APPLS", 10); /* Input Buffer */ 
strncpy (inbuff.name, "SOURCEIBUF", 10); 

strncpy (indesc.library, "UDCS_APPLS", 10); /* Input B Desc */ 


( 

( 

strncpy (indesc.name, "SOURCEBDSC", 10); 
strncpy (outbuff.library, "UDCS_APPLS", 10); /* Output Buffer*/ 
strncpy (outbuff.name, "SOURCEOBUF", 10); 

strncpy (outdesc.library, "UDCS_APPLS", 10); /* Output B Desc */ 
strncpy (outdesc.name, "SOURCEODSC", 10); 

strncpy(qname.library, "UDCS_APPLS", 10); /* Data queue */ 

( 


strncpy(qname.name, "X25DTAQ Mie LO) 5 

[RRRKK retrieve the line description information *****x*/ 
x25lind (&qlind, enable.linename) ; 

if ((qlind.retcode != 0) || (qlind.reason != 0)) 


{ 
printf ("Query line description failed.\n"); 
printf ("Return code = %d\n", glind.retcode) ; 
printf ("Reason code = %d\n\n", gqlind.reason) ; 
return; 
} 
[RRRKK Hard Code the QOLELINK Input Parameters *****x/ 
enable.maxdtax25 = 512; 
enable.keylength = 3; 
strncpy (enable.keyvalue, "SND", 3); 


(4) 


[ORK RK KK KK RK KR A I I I  / 
[RR KKK KKK KKK K Enable the line KK KK KKK RR / 
[ORK RK KK KK KK A I A A A I I OR I K / 


QOLELINK (&(enable.retcode), &(enable.reason), &(enable.tdusize), \ 
&(enable.numunits), &(enable.maxdtalan), & (enable.maxdtax25), \ 
(char *)&inbuff, (char *)&indesc, (char *) &outbuff, \ 

(char *)&outdesc, &(enable.keylength), enable.keyvalue, \ 
(char *)&qname, enable.linename, commhandle) ; 

if ((enable.retcode != 0) | | (enable.reason != 0)) 

{ 

printf ("Line %.10s with Commhandle %.10s was NOT ENABLED. \n", \ 

enable.linename, commhandle) ; 

printf ("Return code = %d\n", enable.retcode) ; 

printf ("Reason code = %d\n\n", enable.reason) ; 

return; 


(5) 


[RSS Sa Set a timer for Enable Link --------- aia A 
expctid = OxFOFO; 
settimer(&expctid, "Enable", &datagq, &qname, commhandle) ; 
if (expctid != OxFOFO) 

{ 

disablelink (&disable, commhandle, &qname) ; 

return, 


} 


(6) 


[BORK KK KK KK KK I AR AA I I I I A A A A A AA A I I I / 


[RR KKK KKK KKK KKK Set up a Cali. Request Packet OK RK KKK KKK KK KK KK / 
[ORK RK KK KK KK I A A I I I A A A A AA AA AA I a Ie / 
fRREX Get pointers to the user spaces. FERRER: 

QUSPTRUS (&o0utbuff, &buffer); 

QUSPTRUS (&outdesc, &descriptor) ; 


send.ucep = 26; /* set the UCEP number */ 
send.operation = 0xBO000; /* send a call request */ 
send.numdtaelmnts = 1; /* send one data unit */ 
[RRS SS SSS SS Send the packet —-------- ae 
sndformatl (&send, buffer, rmtdte, commhandle, &qlind); 
if ((send.retcode != 0) | | (send.reason != 0)) 


{ 

printf ("Call request packet not sent\n"); 
printf ("Return code = %d\n", send.retcode) ; 
printf ("Reason code = %d\n", send.reason) ; 
printf ("new pcep %d\n", send.newpcep) ; 
printespec(&(send.errorspecific) ); 
disablelink (&disable, commhandle, &qname) ; 
return; 


} 
(7) 


[ORK RK KK KK KK KK A A A A A A A A A AA A A I A I / 


[RERERALAAE & Receive the Call CONFIRMATION packet AeA AK). 
[ORK KK KK KK IK A AA IA A A A A A RA IA I A A I / 
[PR eas taeas Set a timer to receive a message --------- HA]: 

expctid = OxFOF3; 

settimer(&expctid, "Rcv Call", &datagq, &qname, commhandle) ; 

if (expctid != OxFOF3) 

{ 

disablelink (&disable, commhandle, &qname) ; 

return; 

} 
QOLRECV (&(recv.retcode), &(recv.reason), &(recv.ucep), \ 
&(recv.pcep), &(recv.operation), &(recv.numdtaunits), \ 
&(recv.dataavail), &(recv.errorspecific), commhandle) ; 
if ((recv.retcode != 0) | | (recv.reason != 0)) 

{ 

printf ("Recv Call reqst resp failed\n"); 

printf ("return code %d\n", recv.retcode) ; 

printf ("reason code %d\n", recv.reason) ; 

printespec (&(send.errorspecific)); 

disablelink (&disable, commhandle, &qname) ; 

return; 

} 

/* Interpret the Received Operation */ 
if (recv.operation != 0xBO01) 

{ 

printf ("Recvd opr %x instead of opr B0O01\n", recv.operation) ; 

disablelink (&disable, commhandle, &qname) ; 

return; 

} 


printf("We have an X.25 SVC connection\n\n"); 


(8) 


[ORK RK KK KK KK AA A A A A A A A A A I A A I / 


[KKKKKKKKAKKKKKK Send the file to the target application *******/ 
[ORK RK KK KK KK A AA IA A A A A A A A I / 
send.pcep = send.newpcep; /* set the PCEP number */ 

[RR KKK KKK KKK KKK K Send the Mbr LGRF in file DOC KKK KK KK RK KK KK / 
linesiz = getline(line, 92, fptr); /* Get first record **/ 


while (linesiz != 0) 
{ 
[RK KKK KKK KK KK KKK Send a Packet of Data KK KK KK KK KK / 
f BREK Get pointers to the user spaces. REAR 
QUSPTRUS (&o0utbuff, &buffer); 
QUSPTRUS (&outdesc, &descriptor) ; 


send.operation = 0x0000; 
send.numdtaelmnts = 1; 
| le Send the packet ** / 
senddata (&send, buffer, descriptor, commhandle, line, linesiz); 
if ((send.retcode != 0) | | (send.reason != 0)) 
{ 
printf ("Data NOT sent for commhandle %.9s\n", commhandle) ; 


( 
printf ("Return code = %d\n", send.retcode) ; 
printf ("Reason code = %d\n", send.reason) ; 
printf ("new pcep d\n", send.newpcep) ; 
printespec (&(send.errorspecific) ); 
disablelink (&disable, commhandle, &qname) ; 
return, 
} 
i=i+i1; 
printf ("Data %d Sent for commhandle %.9s.\n\n", i, commhandle) ; 
linesiz = getline(line, 92, fptr); /** Get next record **/ 
} /*** End While loop ***/ 


[BORK KK KK KK KK KKK IK A AA A A A I I I I / 


[RR KKK KKK KKK KKK K Set up a Clear Request Packet KK KK KK KK KK / 
[KOR KK KK KK KK KK IK I AA A A A I I / 


(9) 


LEEKS Get pointers to the user spaces. a essay 
QUSPTRUS (&o0utbuff, &buffer); 
QUSPTRUS (&outdesc, &descriptor) ; 


send.operation = 0xB100; /** send clear request **/ 
send.numdtaelmnts = 1; /** send one data unit **/ 
[**--==-5=-- = Send the packet --------- ak / 
sndformat2 (&send, buffer, commhandle); 
if ((send.retcode != 0) | | (send.reason != 0)) 

{ 

printf ("Clear request packet not sent\n"); 


( 
printf ("Return code = %d\n", send.retcode) ; 
printf ("Reason code = %d\n", send.reason) ; 
printf ("new pcep d\n", send.newpcep) ; 
printespec (&(send.errorspecific) ); 
disablelink (&disable, commhandle, &qname) ; 


return; 
} 
(10) 
[KOR KK KK KK KK KR IA AA A A A A I / 
[ERE AR AAA BF: Receive the Clear Request Response packet AR ROR Bf 


[BORK KK RK KK KKK KK IA IA A IA A A I 
[RSS e a Set a timer to receive a message ---—------ ne, 
expctid = OxFOF3; 
settimer(&expctid, "Rv Clr Rqt", é&datagq, &qname, commhandle) ; 
if (expctid != 0OxFOF3) 
{ 


disablelink (&disable, commhandle, &qname) ; 


return; 

} 
/*k*k*kkKKX***X Call QOLRECV to Receive the Clear Response *****/ 
[REA A, Get pointers to the user spaces. KK RK / 


QUSPTRUS (&inbuff, &buffer); 

QUSPTRUS (&indesc, &descriptor) ; 

QOLRECV (&(recv.retcode), &(recv.reason), &(recv.ucep), \ 
&(recv.pcep), &(recv.operation), &(recv.numdtaunits), \ 
&(recv.dataavail), &(recv.errorspecific), commhandle) ; 

if ((recv.retcode != 0) | | (recv.reason != 0)) 


{ 
printf ("Recv clear response failed\n"); 
printf ("return code %d\n", recv.retcode) ; 
printf ("reason code %d\n", recv.reason) ; 
printespec(&(send.errorspecific) ); 
disablelink (&disable, commhandle, &qname) ; 
return; 
} 

/* Interpret the Received Operation */ 

if (recv.operation != 0xB101) 
{ 
printf ("Recvd opr %x instead of opr B101\n", recv.operation) ; 
disablelink (&disable, commhandle, &qname) ; 
return; 


} 


[ORK RK KK KK RK I RR I A A KK I K / 


/*** Disable the link and end the program ****/ 
KKK KKK KKK KK KKK KKK KKK KKK KKK KEK KKKKKKKKKKKKKKKKKKK 
/ / 


disablelink (&disable, commhandle, &qname) ; 
printf ("****** SOURCE completed successfully aREKKK\ AN") 7 


} /* End Main */ 
[OK KK RK KK KK KKK IA IA IA IA I I I AA A AAA AA A A I a / 
[RK KKK KKK KKK KKK Start Subroutine Section TK KK KR KK KKK KK Ke / 


[KK RK KK KK KK KKK IR IA IA A I I A A AA AA A A A A / 
[BOK KK KKK KK KK KK A A A A RR A A IA AA OA I A a I e/ 
[RK KKK KK KKK KK KKK Send a Packet of Data TKK KK KK RK KK KK / 


(11) 


void senddata (sendparms *send, 
char *buffer, 
desc *descriptor, 
char *commhandle, 
char *line, 
int linesiz) 


descriptor->length = linesiz; 
descriptor->more = 0; 
descriptor->qualified = 0; 
descriptor->interrupt = 0; 


descriptor->dbit = 0; 
strncpy (buffer, line, linesiz); 
QOLSEND (&(send->retcode), &(send->reason), &(send->errorspecific),\ 
& (send->newpcep), &(send->ucep), &(send->pcep), \ 
commhandle, &(send->operation), &(send->numdtaelmnts) ); 
} /* End senddata Subroutine */ 
[KKK KKK KK KK KK IK IA IA A I I 
[kKKKKKKKKKK* Routine to fill X.25 Format I KKKKKKKE ER / 
void sndformatl (sendparms *send, 
char *buffer, 
char *rmtdte, 
char *commhandle, 
qlindparms *qlind) 


formatl *output = (formatl *) buffer; 

register int counter; 

register querydata *qd; 

qd = (querydata *) &(qlind->userbuffer) ; 
output—>type = 2; /* SVC used */ 
output-—>logchanid = 0x0; 

output—>sendpacksize = qd->x25data.defsend; 
output—>sendwindsize qd->x25data.windowsend; 
output—>recvpacksize = qd->x25data.defrecv; 
output—>recvwindsize = gqd->x25data.windowrecv; 
output—>dtelength = strlen(rmtdte); 

byte (output—>dte, 16, rmtdte, strlen(rmtdte)); 
output-—>dbit = 0; 

output—>cug = 0; 


output—>cugid = 0; 
output->reverse = 
output—>fast = 0; 
output—>faclength = 0; 

byte (output-—>facilities, 109, "", 0); 

output—>calllength = 1; 

byte (output-—>callud, 128, "21", 2); /* Contains Remote PID */ 


0; 


output-—>misc[0] = 0; /* change to 0x80 for reset support */ 
output-—>misc[1] = 0; 

output-—>misc[2] = 0; 

output—>misc[3] = 0; 

output—>maxasmsize = 16383; 


output—>autoflow = 32; 
QOLSEND (&(send->retcode), &(send->reason), &(send->errorspecific),\ 
& (send->newpcep), &(send->ucep), &(send->pcep), \ 
commhandle, &(send->operation), &(send->numdtaelmnts) ); 
} /* End sndformatl Subroutine */ 
[ORK RK KK KKK KK I IA A A A A A A IA A A A I I / 
/kkkkeekeKER Routine to fill X.25 Format II **** eke e HK / 
void sndformat2 (sendparms *send, 
char *buffer, 
char *commhandle) 


format2 *output = (format2 *) buffer; 
output—>type = 1; 

output—>cause = 'FF'; 
output—>diagnostic = 'FF'; 


output—>faclength = 0; 

byte (output-—>facilities, 109, "", 0); 

output—>length = 0; 

byte (output—>userdata, 128, "", 0); 

QOLSEND (&(send->retcode), &(send->reason), &(send->errorspecific),\ 
& (send->newpcep), &(send->ucep), &(send->pcep), \ 
commhandle, &(send->operation), &(send->numdtaelmnts) ); 

} /* End sndformat2 Subroutine */ 


(12) 


[ORK RK KK KK KK KK I I KA I I KR KK A  / 


[RKKKK KKK Routine to disable KKK KK KK KK / 
void disablelink (disableparms *disable, 
char *commhandle, 
usrspace *qname) 
{ 
unsigned short expctid; 
gentry dataq; 
disable->vary = 1; /* Hard coded to be varied off */ 
QOLDLINK (&(disable->retcode), &(disable->reason),\ 
commhandle, &(disable->vary) ); 
if ((disable->retcode != 0) && (disable->reason != 00)) 


{ 
printf ("Link %.10s did not disabled.\n", commhandle) ; 


printf ("return code = %d\n", disable->retcode) ; 
printf ("reason code = %d\n\n", disable->reason) ; 
} 
[MRESASSES Set a timer to receive disable complete msg ------—- ES): 


expctid = OxFOF1; 
settimer(&expctid, "Disable", &dataq, gqname, commhandle) ; 
if (expctid != OxFOF1) 
{ 
printf ("Disable link did not complete successfully"); 
return; 
} 
printf ("%.10s link disabled \n", commhandle) ; 
/** close the files **/ 
fclose(fptr); 
fclose (screen); 


} /* End disablelink Subroutine */ 
[OK KK KK KK KK KK KK IK IA AA A A A AR A A A oe / 
poor Routine to convert string to Hexadecimal format REE KEY, 
void byte (char *dest, 

int dlength, 

char *source, 

int slength) 


register int counter; 
char holder[2]; 
for (counter=0; counter<dlength; counter++) 
dest [counter]=0; 
for (counter=slength-1; counter>=0; counter-——) 
if (isxdigit (source[counter])) 
{ 
holder [0]=source [counter]; 
holder[1]='\0'; 
if (counter % 2 == 0) 
dest [counter/2] += ( 
else dest[counter/2] + 
} 
} /* End byte Subroutine */ 


KKK KK KKK KK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KK KKK KKK KKKKKKKKKKKKKKK 
/ i 
a Routine to display the ErrorSpecific output Re AEE fp 
void printespec(espec *errorspecific) 


{ 


especout outparms; 


char) hextoint (holder) *16; 
= (char) hextoint (holder) ; 


sprintf (outparms.hwecode, "%.8X", errorspecific—>hwecode) ; 

sprintf (outparms.timestamp, "%.8X%.8X", errorspecific-—>timestamphi, \ 
errorspecific—>timestamplo) ; 

sprintf (outparms.elogid, "%.8X", errorspecific—>elogid) ; 

if (errorspecific->flags & 0x40) 


outparms.fail = 'Y'; 

else outparms.fail = 'N'; 

if (errorspecific->flags & 0x20) 
outparms.zerocodes = 'Y'; 

else outparms.zerocodes = 'N'; 

if (errorspecific->flags & 0x10) 
outparms.qsysopr = 'Y'; 

else outparms.qsysopr = 'N'; 


sprintf (outparms.cause,"%.2X", errorspecific—>cause) ; 
sprintf (outparms.diagnostic, "%.2X", errorspecific—>diagnostic); 
sprintf (outparms.erroffset, "%.6d", errorspecific—>erroroffset); 
fwrite(&outparms, 1, sizeof (especout), screen) ; 
fread("", 0, O, screen); 

} /* End printespec Subroutine */ 

(13) 


[RRRRKRKKKKRR ERK Set a timer and dequeue next entry ******/ 
void settimer (unsigned short *expctid, 
char *process, 
gentry *dataq, 
usrspace *qname, 
char *commhandle) 
{ 
timerparms timer; 
disableparms disable; 
int length; 
char key[6]; 


timer.interval = 20000; /* Set timer for 20 seconds */ 
timer.establishcount = 1; 

timer.keylength = 3; /* Set key value */ 

strncpy (timer.keyvalue, "SRC", 3); 

timer.operation = 1; /* Set a timer */ 


QOLTIMER (&(timer.retcode), &(timer.reason), timer.handleout, \ 
timer.handlein, (char *)qname, &(timer.operation), \ 


&(timer.interval), &(timer.establishcount), \ 
&(timer.keylength), timer.keyvalue, timer.userdata) ; 
if ((timer.retcode != 0) || (timer.reason != 0)) 


{ 


printf("%s timer failed while being set.\n", process); 
printf ("Return code = %d\n", timer.retcode) ; 


printf ("Reason code = %d\n\n", timer.reason); 
} 
[RRS ss Ie Dequeue an entry -—------- atl 


strncpy (key, "SRC",3); 
length = 3; 

dequeue (length, key, dataq, qname) ; 

/*** Cancel timer ***/ 

if (dataq->msgid != OxFOF4) 

{ 

strncpy(timer.handlein, timer.handleout, 8); 

timer.operation = 2; /* Set one timer */ 

QOLTIMER (&(timer.retcode), &(timer.reason), timer.handleout, \ 
timer.handlein, (char *)qname, &(timer.operation), \ 
&(timer.interval), &(timer.establishcount),\ 
&(timer.keylength), timer.keyvalue, timer.userdata) ; 

if ((timer.retcode != 0) || (timer.reason != 0)) 

{ 
printf("%s timer failed while being canceled\n", process); 
printf ("Return code = %d\n", timer.retcode) ; 
printf ("Reason code = %d\n\n", timer.reason) ; 
} 
} 
if (dataq->msgid != *expctid) 
{ 
printf ("A %.4X message ID was received instead of %.4X\n",\ 
dataq->msgid, *expctid); 

printf ("Ss completion message was not received\n", process) ; 

*expctid = dataq->msgid; 

} 


} /* End settimer Subroutine */ 
[OK KK KK KKK KK KKK IR IR IA IA A I I I A A A A He / 


LRERERAA Dequeues the Incoming Message and processes it ******/ 
void dequeue (int length, 

char *key, 

gentry *dataq, 

usrspace *qname) 


char fldlen[3], 
waittime[3], 

l, 

[2 


keylen[2 
senderid[2], 
*pointer, 
order [2]; 
register int counter; 
waittime[0] = 0; 
waittime[1] = 0; 
waittime[2] = 0x1D; /* Hard code a delay of infinite * / 
keylen[0] = 0; 
keylen[1] = 0x3F; /* Hard code a keylength of 3 */ 
senderid[0] = 0; 
senderid[1] = Ox0OF; 


strncpy (order, "EQ", 2); 
fflush(stdin); 


pointer = (char *)dataq; 
for (counter = 0; counter < 336; counter+tt) 
pointer[counter] = 0; 
strncpy (dataq->type, " wep: AA) 
while ((strncmp(dataq->type, "*USRDFN", 7) != 0) | | (fldlen == 0)) 
QRCVDTAQ(qname->name, qname->library, fldlen, datag, waittime, \ 
order, keylen, key, senderid,""); 


} /* End dequeue Subroutine */ 
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[ORK RK KK KKK KK KK KK IA IA A I A AK A He  / 
/** x25lind: Retrieve X.25 line description information **/ 
void x25lind (qlindparms *qlind, char *linename) 
{ 
register int counter; 
for (counter=0; counter<256; counter+t) 
qlind->userbuffer [counter] =0; 
qlind->format = 0x01; 
QOLQLIND (&(qlind->retcode), &(qlind->reason), &(qlind->nbytes),\ 
gqlind->userbuffer, linename, &(qlind->format) ); 
} /* End x25lind Subroutine */ 
[KK RK KKK KK I IK A A A I RR A A A I I / 
/** Getline: Read a record into line and return length say A 
int getline (char *line, int max, FILE *fptr) 
{ 
if (fgets(line, max, fptr) == NULL) 
return 0; 
else 
return strlen(line) ; 


} /* End getline Subroutine */ 
KKK KK KK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKKKKKKKKKKKKKK 
/ / 


Source application program listing references 


The following reference numbers and explanations correspond to the reference numbers in the source application's program listing. 


(1) Some general C structure declarations used by both the source and target application programs. 
(2) Function prototypes of the internal functions used in this program. 


(3) Call the C library routines fopen() and signal() to open the source file and set up a signal handler to process OS/400 
exceptions, respectively. An example of an exception would be accessing a data area with a NULL pointer. If an exception 
situation is encountered, SIG_DFL, the default handler, will be called in order for the program to end. 


(4) Call the QOLQLIND API to retrieve local configuration information from the iSeries server line description about that will be 
used for communications. Next, call the QOLELINK API to enable the line description using the line name and 
communications handle passed as input parameters to this program. 


(5) Call the QOLTIMER API to time the completion of the enable link operation. If the timer expires before the enable-complete 
entry is posted on the this program's data queue, then this program will end. 


(6) Call the QOLSEND API with a X'B000' operation to establish a connection to the target application program. 


(7) Monitor the source program's data queue for the call confirmation. The source program will be notified of the call 
confirmation by call the QOLRECV API and receiving a X'BOO!' operation in the program's input buffer. 


(8) This is the main send loop for the source program. The data from the source file is placed one line at a time in the output 
buffer and then the QOLSEND API is called to send one data unit of the file to System B. This process repeats until the 
contents of the entire file have been transmitted to the target application. 


(9) Call the QOLSEND API with a X'B 100' operation to clear the peer connection. 


(10) The source program will check its data queue for a response to the clear packet sent to the target system. Once the response is 
received, the program will clean up, call the QOLDLINK API to disable the link previously enabled, and end. 


(11) The following C functions illustrate the various user-defined communications support APIs. 


(12) This procedure illustrates a call to the QOLDLINK API. Note the vary option is set to vary off the associated iSeries server 
*USRDEN network device. 


(13) The settimer() calls the QOLTIMER API requesting timers for 20000 milliseconds, or twenty seconds. After setting a timer, 
the settimer() will call the dequeue() to remove an entry from the program's data queue. 


(14) The x25lindQ) illustrates calling the QOLQLIND API. 


Target Application on System B Listing 


The target application waits for the source application to initiate the file transfer. The following list summarizes the actions of the 
target application: 


e Calls the QOLQLIND API to get local X.25 line information 

@ Opens the local file 

e Calls the QOLELINK API to establish a link for communications 

@ Calls the QOLSETF API to activate an X.25 protocol ID filter 

e Calls the QOLRECV API to receive the X'B201' operation (incoming call) 

@ Calls the QOLSEND API with a X'B400' operation to accept the SVC connection 
e Receives the file from the target system using X'0001' operations 

e@ Calls the QOLRECV API to receive the X'B301' (connection failure notification) 

e@ Call the QOLSEND API with 'B100' operation to locally close the SVC connection 
e Calls the QOLDLINK API to disable the link 


@ Calls the QOLTIMER API to manage the reception of data queue entries 
To create the program using ILE C, use the Create Bound C (CRTBNDC) command. 


Explanations of the reference numbers in the listing can be found in Target application program listing references. 


Program name ........ . : (TARGET) 
Library name ........3: UDCS_APPLS 
Source ‘file «6 8 Bw we aoa se QCSRC 
Library name ........3: UDCS_APPLS 
Source member name ......: TARGET 
Text Description ..... . . : Target Application Example 
QUEDUE. sw SG oe we ew Se ee 8 *NONE 
Compiler options : *SOURCE *NOXREF *NOSHOWUSR 
*NOSHOWSYS *NOSHOWSKP *NOEXPMAC 
*NOAGR *NOPPONLY *NODEBUG 
*GEN *NOSECLVL *PRINT *LOGMSG 
*USRINCPATH 
Checkout Options *NOAGR 
Optimization *NONE 
Inline Options: 
Inliner *OFF 
Mode *NOAUTO 
Threshold 250 
Limit , 2000 
Debugging View *NONE 
Define Names ty Be eA a ee *NONE 
Language Level ........: * SOURCE 
Source Margins: 
Left margin « « 2 2% % « «.« 4 1 
RiGhe Margin 2. si % Ye ws ow oo 8 32754 
Sequence columns: 
Left column 2.4 2 « « #42 «2 « 3 *NONE 
Right column ........: 
Message flagging level ....: 0 
Compiler messages: 
Message limit ........: *NOMAX 
Message limit severity ...: 30 
Replace Program Object ....: *YES 
User Profile .........3: *USER 
AUtHOLTIEVy 4 wo we . Gow wee a a we 8 *LIBCRTAUT 
Target Release ........3 *CURRENT 
System includes ........: *YES 


[ORK RK KK KKK KK IK AA IA A A A A AA AA A A A A I A I I He / 
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Program Name: Target Application Program Example 


Function: 

This is the target application program example that uses 
X.25 services provided by the user-defined communications 
support to receive a simple file from the source application 
program running on System A. This program performs the 
following: 

O01. Open the target file named OUTFILE. 

02. Call QOLQLIND to obtain local line information. 

03. Enable a link. 

04. Set a Filter on the enabled link. 

05. Receive a 'B101'X operation (incoming call). 

06. Send a 'B400'X operation (accept call). 

07. Receive '0001'X operation(s) (incoming data) from 
the source application program and write it to the 
file opened in step 1). 

08. Receive a 'B301'X operation (clear call indication). 
09. Send a 'B100'X operation to respond locally to the 
clearing of the connection. 

10. Disable the link enabled in step 3). 


A data queue will be actively used to manage the operation 
of this program. Data queue support will be used to monitor 
for the completion of the enable and disable routines, as 
well as timer expirations and incoming data. Timers are 
used to ensure that there will never be an infinite wait on 
the data queue. If a timer expires, the link enabled will 
be disabled and the program will stop. 


Inputs: 
The program expects the following input parameters: 


Line Name: This is the name of the line description 
that will be used to call the QOLELINK API. 
The line must be an X.25 line with at least 
one SVC of type *SVCBOTH or *SVCIN. 
CommHandle: This is the logical name that will be used 
to identify the link enabled. 
Remote DTE Address: The is the Local Network Address 
of system A. 
Outputs: 
Current status of the file transfer will be provided when 


running this program. If an error should occur, then a 
message will be displayed indicating where the error occurred 
and the program will end. If the program completes 
successfully, a "successful completion" message will be 
posted. 


Language: ILE C for OS/400 


APIs used: QOLELINK, QUSPTRUS, QOLRECV, QOLSEND, QOLDLINK, 
QRCVDTAQ, QOLTIMER 


xx / 
xx / 
xx / 
xx / 
xx / 
xx / 
xx / 
xx / 
xx / 
xx / 
xx / 
xx / 
xx / 
x* / 
x* / 
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[KK RK KK KK KK KI IK IA A A A A AA A IA A A A I A I I / 


[KK RK KK KKK KK KK IR A A A A RA AIA A A A I A IH / 


[RK RK KK KK KK KK A IA A A A A IA IA IA A I A I A I I / 


[KK RK KK KK KK KK A A A A A RA AA A AA A I A I A I I I 


#include "header" 


#include "typedef" 
#include "hexconv" 


void senddata(sendparms *a, char *b, desc *c, char *d, char *e, int f); 
void sndformatl(sendparms *a,char *b, char *c, char *d, qlindparms *e); 


void sndformat2 (sendparms *a, char *b, char *c); 
void setfilters (hdrparms *a); 

void byte (char *a, int b, char *c, int d); 

void printespec (espec *a); 


void settimer(unsigned short *a,char *b,qentry *c,usrspace *d,char *e); 


void dequeue (int a, char *b, gentry *c, usrspace *d); 
void putdata (char *a, int b, FILE *c); 

void x25lind (qlindparms *a, char *b); 

void disablelink (disableparms *a, char *b, usrspace *c)j; 
void handler (disableparms a, usrspace *b); 


void _GetExcData(_INTRPT_Hndlr_Parms_T *parms) ; 
[OK KK KK KK KKK I AA A A A RR A OR AA A A A I 


[RK KKK KK KKK KK KKK Start Main Program TKK KK  / 
[OK KK KK KK KK I A A A AR A A A A  e/ 
main (int argc, char *argv[]) 


{ 


[RK KKK KK KKK KK Variable Declarations TK eK KK KK KK / 
usrspace inbuff, /* Input Data Buffer */ 
indesc, /* Input Buffer Descriptor */ 
outbuff, /* Output Data Buffer */ 
outdesc, /* Output Buffer Descriptor */ 
qname; /* Data Queue */ 
int length, /* Data Queue key length */ 
tne, ay. ae /* counters */ 
unsigned short expctid; /* Message ID that is expected */ 
char commhandle[10], /* Command Line Parameter */ 
rmtdte[17], /* Remote DTE Address */ 
*buffer, /* Pointer to buffer */ 
key[256]; /* Data Queue key identifier */ 
desc *descriptor; /* Pointer to buffer descriptor */ 


/** definitions for API functions **/ 
enableparms enable; 
disableparms disable; 
sendparms send; 
recvparms recv; 
setfparms setf; 
timerparms timer; 
qlindparms qlind; 
gentry dataq; 
hdrparms *header; 


/****** Annndddddd.... they're off]! — **#*eeKEERK/ 

(1) 
/***x---— Open the file to put the received data. are Le / 
if ((fptr = fopen("UDCS_APPLS/OUTFILE))", "w")) == NULL) 


{ 


printf ("Unable to open target output file in UDCS_APPLS LIB.\n"); 


printf ("The Program was terminated.\n\n"); 


return, 

} 
/***---— Open the display file for error handling. Snake / 
if ((screen = fopen("ERRORSPEC", "ab+ type = record")) == NULL) 


{ 
printf ("Unable to open display file.\n"); 
printf ("The Program was terminated.\n\n"); 
return; 
} 

/***---— Set the Exception Handler —- Ake / 


signal (SIGALL,SIG_DFL); 
/** Clear the command line parameters **/ 


strncpy (enable.linename, " mele OD Yer /* Clear linename */ 


strncpy(commhandle, " We. 10) *3 /* Clear Commhandle */ 
strncpy(rmtdte, " Me ACTF /* Clear Remote DTE */ 
/** Receive command line Parameters **/ 

strncpy (enable.linename, argv[1], strlen(argv[1])); 
strncpy(commhandle, argv[2], strlen(argv[2])); 

strncpy(rmtdte, argv[3], strlen(argv[3])); 

rmtdte[strlen(argv[3])] = '\0'; 

/** Initialize the user spaces **/ 

strncpy (inbuff.library, "UDCS_APPLS", 10); /* Input Buffer */ 
strncpy(inbuff.name, "TARGETIBUF", 10); 
strncpy (indesc.library, "UDCS_APPLS", 10); /* Input B Desc */ 
strncpy(indesc.name, "TARGETIDSC", 10); 

strncpy (outbuff.library, "UDCS_APPLS", 10); /* Output Buffer*/ 
strncpy (outbuff.name, "TARGETOBUF", 10); 
( 
( 
( 
( 


strncpy (outdesc.library, "“UDCS_APPLS", 10); /* Output B Desc */ 
strncpy (outdesc.name, "TARGETODSC", 10); 
strncpy(qname.library, "UDCS_APPLS", 10); /* Data queue */ 


strncpy(qname.name, "X25DTAQ (20): 

[RREKK retrieve the line description information ******/ 
x25lind (&qlind, enable.linename) ; 

if ((qlind.retcode != 0) || (qlind.reason != 0)) 


{ 
printf ("Query line description failed.\n"); 
printf ("Return code = %d\n", glind.retcode) ; 
printf ("Reason code = %d\n\n", gqlind.reason); 
return; 
} 

[RRRKK Hard Code the QOLELINK Input Parameters *****x*/ 

enable.maxdtax25 = 512; 

enable.keylength = 3; 

strncpy (enable.keyvalue, "RCV", 3); 

(2) 


[**------— Enable the link ----------- **/ 

QOLELINK (&(enable.retcode), &(enable.reason), &(enable.tdusize), \ 
&(enable.numunits), &(enable.maxdtalan), & (enable.maxdtax25),\ 

(char *)&inbuff, (char *)&indesc, (char *) &outbuff,\ 

(char *)&outdesc, &(enable.keylength), enable.keyvalue, \ 

(char *)&qname, enable.linename, commhandle) ; 

( 


if ((enable.retcode != 0) | | (enable.reason != 0)) 
{ 
printf ("Line %.10s with Commhandle %.10s was NOT ENABLED. \n", \ 

enable.linename, commhandle) ; 
printf ("Return code = %d\n", enable.retcode) ; 
printf ("Reason code = %d\n\n", enable.reason) ; 
return, 
} 
(3) 
[PRS HSS Set a timer for Enable link ---—---—- RR) 


expctid = OxFOFO; 
settimer(&expctid, "Enable", &datag, &qname, commhandle) ; 
if (expctid != OxFOFO) 

{ 

disablelink (&disable, commhandle, &qname) ; 

return, 


} 


[ORK RK KK KK KK KK A A I A A A A A A A I He / 


/***k****---- Set a Filter for the Link ------—- PEN f. 
[ORK RK KK KK KK I A A A A I A A A A A I A 


(4) 


QUSPTRUS (&é0utbuff, &header) ; /* get the output buffer pointer */ 


header->function = 1; /* adda filter aA 
header->type = 0; /* X.25 PID only */ 
header->number = 1; /* set 1 filter af 


header->length = 16; /* X.25 filter length */ 


setfilters (header) ; /* Fill in the filter format */ 
/****k*k*kk---- Set the filter for the Link -------- RAK KKK KKK / 
QOLSETF (&(setf.retcode), &(setf.reason), &(setf.erroffset),\ 
commhandle) ; 
if ((setf.retcode != 0) | | (setf.reason != 0)) 
{ 
printf("Set Filters Return Code = %.2d\n", setf.retcode) ; 
printf("Set Filters Reason Codes %.4d\n", setf.reason); 
printf ("Set Filters Error Offset %.4d\n", setf.erroffset) ; 
return; 


} 


[ORK RK KK KK KK KK A A A I I I A A A A A A / 


/**** Receive the incoming call packet and accept the call **/ 
[ORK RK KK KK KK I I A A I I I A A A A A / 


[ONES Aaa Set a timer to receive data -------- sass 
expctid = OxFOF3; 
settimer(&expctid, "Inc Call ", &datag, &qname, commhandle) ; 
if (expctid != O0xFOF3) 
{ 
disablelink (&disable, commhandle, &qname) ; 
return; 
} 
(5) 


[*kkKkKKKKKK Receive the Incoming Data RREKRK KERR RK / 
QUSPTRUS (&inbuff, &buffer); 
QUSPTRUS (&indesc, &descriptor) ; 
QOLRECV (&(recv.retcode), &(recv.reason), &(recv.ucep), \ 
&(recv.pcep), &(recv.operation), &(recv.numdtaunits), \ 
&(recv.dataavail), &(recv.errorspecific), commhandle) ; 
if ((recv.retcode != 0) | | (recv.reason != 0)) 
{ 
printf ("Recv incoming call packet failed\n"); 
printf ("return code %d\n", recv.retcode) ; 
printf ("reason code %d\n", recv.reason) ; 
printespec (&(send.errorspecific) ); 
disablelink (&disable, commhandle, &qname) ; 
return; 
} 

/*x* Interpret the Received Operation ***/ 

if (recv.operation != 0xB201) 
{ 
printf ("Recvd operation %x instead of B201", recv.operation) ; 
disablelink (&disable, commhandle, &qname) ; 
return; /**** End the program ***/ 


} 


(6) 


[BORK KK KK KK KK I A A A A I A A A A A AA AA A I I / 


/** Send a response to accept the call and establish a connection */ 
[BORK RK KK KK KK KK I A AA I I I I A A A AA A A I I I a / 
[ee REX Get pointers to the user spaces. ERRERE SY 

QUSPTRUS (&o0utbuff, &buffer); 

QUSPTRUS (&outdesc, &descriptor) ; 


[RRKKKKK Set up Send Packet KK RK KK / 
send.ucep = 62; /* set UCEP to be 62 */ 
send.pcep = recv.pcep; /* get the PCEP number */ 
send.operation = 0xB400; /* send a call request response*/ 
send.numdtaelmnts = 1; /* send one data unit sa A 
[RRS SSS Send the packet sais 
sndformatl (&send, buffer, rmtdte, commhandle, &qlind); 
if ((send.retcode != 0) | | (send.reason != 0)) 

{ 

printf ("Data NOT sent for commhandle %.9s\n", commhandle) ; 

printf ("Return code = %d\n", send.retcode) ; 

printf ("Reason code = %d\n", send.reason) ; 

( 


printf ("new pcep Sd\n\n", send.newpcep) ; 


printespec (&(send.errorspecific) ); 
disablelink (&disable, commhandle, &qname) ; 
return; 
} 
printf ("An X.25 SVC connection was completed\n\n"); 


(7) 


[ORK KK RK KK KK I AA I A I A A A A A / 


[KKK Receive Incoming Data TKK KR KR I  / 
[KOR KK KK KK KR KR A A I I A A I  / 
[RABI SES Set a timer to receive data -------- Kok 

expctid = OxFOF3; 

settimer(&expctid, "Inc Data ", &datag, &qname, commhandle) ; 

if (expctid != 0xFOF3) 

{ 

disablelink (&disable, commhandle, &qname) ; 
return; 

} 

/**xxx**x*k--- Receive the Incoming Data SSSSERE AAS / 

/** Get pointer to user space **/ 

QUSPTRUS (&inbuff, &buffer); 

QUSPTRUS (&indesc, &descriptor) ; 

/** Receive the data Pay), 

QOLRECV (&(recv.retcode), &(recv.reason), &(recv.ucep), \ 
&(recv.pcep), &(recv.operation), &(recv.numdtaunits), \ 
&(recv.dataavail), &(recv.errorspecific), commhandle) ; 

if ((recv.retcode != 0) | | (recv.reason != 0)) 

{ 

printf("Recv op for first data unit failed\n"); 
printf ("return code %d\n", recv.retcode) ; 
printf ("reason code %d\n", recv.reason) ; 
printespec (&(send.errorspecific) ); 

disablelink (&disable, commhandle, &qname) ; 
return; 


} 


(8) 


[ORK KK KK KK KK IR AA A A A A A RA A I I A / 


/******* Start a loop to read in all the incoming data wa | 
[ORK RK KK KK KK KK A A A A A A A  / 
i=1; 
while (recv.operation == 0x0001) 

{ 

printf("%d Data Recvd {%.4x}.\n\n", i++, recv.operation) ; 

/** Store all the data units in the file **/ 

for (j = 1; j <= recv.numdtaunits; jtt) { 

putdata (buffer + (j - 1)*enable.tdusize, \ 
descriptor->length, fptr); 


descriptor = (desc *) ((char *)descriptor + sizeof(desc)); 
} [RV ELOL. */ 
[ERSER ESAS Set a timer to wait for more data ------- ase A 


if (recv.dataavail == 0) 
{ 
/** Set timer **/ 
expctid = OxFOF3; 
settimer(&expctid, "Wt Inc Dta", é&datagq, &qname, commhandle) ; 
if (expctid != OxFOF3) 
{ 
disablelink (&disable, commhandle, &qname) ; 
return; 
} 
} 
/** Get pointer to user space **/ 
QUSPTRUS (&inbuff, &buffer); 
QUSPTRUS (&indesc, &descriptor) ; 


/** Receive the data baa A 

QOLRECV (&(recv.retcode), &(recv.reason), &(recv.ucep), \ 
&(recv.pcep), &(recv.operation), &(recv.numdtaunits), \ 
&(recv.dataavail), &(recv.errorspecific), commhandle) ; 

} /** End Receive data while loop ile seal A 


(9) 


[BORK RK KK KK KK KR A A I A I I I / 


[kkKKKKKKKKK Receive the Clear indication *********xx/ 
[ORK KK KK KK KR A A I I I 
if ((recv.retcode != 83) | | (recv.reason != 4002) ) 
{ 
printf ("Recv opr for clear request failed\n"); 
printf ("return code %d\n", recv.retcode) ; 
printf ("reason code %d\n", recv.reason) ; 
printespec (&(send.errorspecific) ); 
disablelink (&disable, commhandle, &qname) ; 
return; 
} 
/* Interpret the Received Operation */ 
if (recv.operation != 0xB301) 
{ 
printf ("Recvd operation %x instead of B301", recv.operation) ; 
disablelink (&disable, commhandle, &qname) ; 
return; /**** end the program ***/ 


} 


(10) 


[ORK KK KK KK A I A A A I A A A A A A A A I e/ 


/*k*kk*kk*Xe**X Send local response to clear indication **********x/ 
[ORK RK KK KK KK KK A A A A A I A A A A A A I 
VASES iNC es Get pointers to the user spaces. RA fs 

QUSPTRUS (&o0utbuff, &buffer); 

QUSPTRUS (&outdesc, &descriptor) ; 


[RRKKKKK Set up the packet KK KK KKK KKK KK KK / 
send.operation = 0xB100; /* send a clear request packet */ 
send.numdtaelmnts = 1; /* send one data unit */ 

[ka sS5= Send the packet saat 4 

sndformat2 (&send, buffer, commhandle); 

if ((send.retcode != 0) && (send.reason != 0)) 


{ 

printf ("Response not sent for clear connection\n") ; 
printf ("Return code = %d\n", send.retcode) ; 

printf ("Reason code = %d\n", send.reason) ; 

printf ("new pcep Sd\n\n", send.newpcep) ; 
printespec(&(send.errorspecific) ); 

disablelink (&disable, commhandle, &qname) ; 

return; 


} 


[BORK KK RK KK KK KK I AA A A A A I KK K / 


[*xeexKKAKE* Receive the Clear Confirmation *****x*4*%%/ 
[BORK RK KK KK KK I A A A A A I I  / 
[PRESS SSS Set a timer to receive data -------- tay f 
expctid = OxFOF3; 
settimer(&expctid, "Clr Cnfrm", &datag, &qname, commhandle) ; 
if (expctid != O0xFOF3) 

{ 

disablelink (&disable, commhandle, &qname) ; 

return; 

} 
if ((recv.retcode != 00) | | (recv.reason != 0000) ) 

{ 

printf ("Recv failed for clear confirmation\n"); 

printf ("return code %d\n", recv.retcode) ; 

printf ("reason code %d\n", recv.reason) ; 


printespec (&(send.errorspecific) ); 
disablelink (&disable, commhandle, &qname) ; 
return; 
} 
/* Interpret the Received Operation */ 
if (recv.operation != 0xB101) 
{ 
printf ("Recvd opr %x instead of opr B301\n", recv.operation) ; 
disablelink (&disable, commhandle, &qname) ; 
return; 


} 
(11) 


[ORK KK RK KK KK A OO  / 


/** disable the link and end program **/ 


[ORK RK KK KK KK A O  / 


disablelink (&disable, commhandle, &qname) ; 
printf ("TARGET application completed OK!\n\n"); 


} /* End Main */ 
[OK KK KK KKK KK KK IA IA IA IA I AR AAA A A A A / 
[RK KKK KKK KKK KKK Start Subroutine Section TKK KK KK KK KKK KK KK / 


[KK RK KK KK KK KK A A AA A I AA A A A A a A a / 
[KK RK KK KK KK KKK IR IA IA A I I AA AIA A I A A A / 


[kxxKKKKKKKKK* Routine to fill X.25 Format I KRKKKKKER EK / 
void sndformatl (sendparms *send, 

char *buffer, 

char *rmtdte, 

char *commhandle, 

qlindparms *qlind) 


formatl *output = (formatl *) buffer; 

register int counter; 

register querydata *qd; 

qd = (querydata *) &(qlind->userbuffer) ; 
output—>type = 0; /* not used */ 
output-—>logchanid = 0x0; 

output—>sendpacksize = gqd->x25data.defsend; 
output—>sendwindsize qd->x25data.windowsend; 
output—>recvpacksize = gqd->x25data.defrecv; 
output—>recvwindsize = qd->x25data.windowrecv; 


output—>dtelength = strlen(rmtdte); /* not used */ 
byte (output-—>dte, 16, rmtdte, strlen(rmtdte)); /* not used */ 
output—>dbit = 0; 

output—>cug = 0; /* not used */ 
output—>cugid = 0; /* not used */ 
output—>reverse = 0; /* not used */ 
output—>fast = 0; /* not used */ 


output—>faclength = 0; 

byte (output-—>facilities, 109, "", 0); 
output—>calllength = 0; 

byte (output—>callud, 128, "00", 2); 


output-—>misc[0] = 0; 
output-—>misc[1] = 0; 
output—>misc[2] = 0; 
output-—>misc[3] = 0; 


= v 
output-—>maxasmsize = 16383; 
output—>autoflow = 32; 
QOLSEND (&(send->retcode), &(send->reason), &(send->errorspecific),\ 
& (send->newpcep), &(send->ucep), &(send->pcep), \ 
commhandle, &(send->operation), &(send->numdtaelmnts) ); 
} /* End sndformatl Subroutine */ 
[KK RK KK KKK KK KKK IA AA AA IA I A AA A IA A A A / 
/ekeeeeKEKER Routine to fill X.25 Format II ***** kkk / 
void sndformat2 (sendparms *send, 
char *buffer, 
char *commhandle) 


format2 *output = (format2 *) buffer; 

output—>type = 1; 

output—>cause = 'FF'; 

output—>diagnostic = 'FF'; 

output—>faclength = 0; 

byte (output-—>facilities, 109, "", 0); 

output—>length = 0; 

byte (output—>userdata, 128, "", 0); 

QOLSEND (&(send->retcode), &(send->reason), &(send->errorspecific),\ 
& (send->newpcep), &(send->ucep), &(send->pcep), \ 
commhandle, &(send->operation), &(send->numdtaelmnts) ); 


} /* End sndformat2 Subroutine */ 
[OK KK KK KK KKK KK IK IA IA IA I I AA AA AAA IA A A I I A / 


[RK KKK KKK KKK KKK Fill in the Buffer for the Filter KK KK KK KK KK KK  / 
void setfilters (hdrparms *header) 


{ 
x25filter a eee 


filters = (x25filter *)header->filters; 

filters[0].pidlength = 1; 

filters[0].pid = 0x21; /* set the protocol ID */ 
filters[0].dtelength = 0; /* no DTE used in filter */ 
byte (filters[0].dte, 12, "", 0); 

filters[0].flags = 0x0; 

filters[0].flags += 0x80; /* Set Reverse Charging to no */ 
filters[0].flags += 0x40; /* Set Fast Select to no */ 


} /* End setfilters Subroutine */ 
[KK RK KKK KK KK KK A A I I  / 
[RKKKK KKK Routine to disable KKK KKK KK KK / 
void disablelink (disableparms *disable, 

char *commhandle, 

usrspace *qname) 


gentry dataq; 

unsigned short expctid; 

disable->vary = 1; /* Hard code device to vary off */ 
/** Call disable link **/ 


QOLDLINK (&(disable->retcode), &(disable->reason),\ 
commhandle, &(disable->vary) ); 
if ((disable->retcode != 0) && (disable->reason != 00)) 


{ 
printf ("Link %.10s did not disabled.\n", commhandle) ; 


printf ("return code = %d\n", disable->retcode) ; 

printf ("reason code = %d\n\n", disable->reason) ; 

} 
else 

printf ("%.10s link disabled \n", commhandle) ; 
[RRS SSSH SS Set a timer to receive message -------- we 
expctid = OxFOF1; 
settimer(&expctid, "Disable ", &datag, qname, commhandle) ; 
if (expctid != OxFOF1) 


{ 
printf ("Disable link did not complete successfully"); 


return; 
} 
/** close the files **/ 
fclose(fptr); 
fclose (screen); 
} /* End disablelink Subroutine */ 
[KK RK KKK KK KK KK AA AA IA A A A A A A oe / 
lea Routine to convert string to Hexadecimal format RRR KK / 
void byte (char *dest, 
int dlength, 
char *source, 
int slength) 


register int counter; 


char holder[2]; 
for (counter=0; counter<dlength; counter++) 
dest [counter]=0; 
for (counter=slength-1; counter>=0; counter——) 
if isxdigit (source[counter]) 
{ 
holder [0]=source [counter]; 
holder[1]='\0'; 
if (counter % 2 == 0) 
dest [counter/2] += (char) hextoint (holder) *16; 
else dest [counter/2] += (char) hextoint (holder); 
} 
} /* End byte Subroutine */ 


[KKK RK KKK KK KKK A IA A A A A A A A A a / 


[ee Routine to display the ErrorSpecific output ROCA Tete 
[KKK KR KKK KK A IA IA IA A A A A AA A I a / 
void printespec(espec *errorspecific) 

{ 


especout outparms; 


sprintf (outparms.hwecode, "%.8X", errorspecific—>hwecode) ; 

sprintf (outparms.timestamp, "%.8X%.8X", errorspecific-—>timestamphi, \ 
errorspecific—>timestamplo) ; 

sprintf (outparms.elogid, "%.8X", errorspecific—>elogid) ; 

if (errorspecific->flags & 0x40) 


outparms.fail = 'Y'; 

else outparms.fail = 'N'; 

if (errorspecific->flags & 0x20) 
outparms.zerocodes = 'Y'; 

else outparms.zerocodes = 'N'; 

if (errorspecific->flags & 0x10) 
outparms.qsysopr = 'Y'; 

else outparms.qsysopr = 'N'; 


sprintf (outparms.cause,"%.2X", errorspecific—>cause) ; 
sprintf (outparms.diagnostic, "%.2X", errorspecific—>diagnostic); 
sprintf (outparms.erroffset, "%.6d", errorspecific—>erroroffset) ; 
fwrite(&outparms, 1, sizeof (especout), screen); 
fread("", 0, 0, screen); 
} /* End printespec Subroutine */ 
[BOR KK KK KKK KKK KR IR IA IA IA I I I A A A A 
[ORE AAS Ke Dequeues the Incoming Message and processes it ******/ 
void dequeue (int length, 
char *key, 
gentry *dataq, 
usrspace *qname) 


char fldlen[3 


l, 

waittime[3], 

keylen[2], 

senderid[2], 

*pointer, 

order [2]; 
register int counter; 
waittime[0] = 0; 
waittime[1] = 0; 
waittime[2] = 0x1D; /* Hard code a delay of infinite */ 
keylen[0] = 0; 
keylen[1] = 0x3F; /* Hard code a keylength of 3 */ 
senderid[0] = 0; 
senderid[1] = Ox0OF; 


strncpy (order, "EQ", 2); 

/* Clear the data structures **/ 

fflush(stdin); 

pointer = (char *)dataq; 

for (counter = 0; counter < 336; countert+tt) 
pointer[counter] = 0; 

strncpy (dataq->type, " mp Ah) 


while ((strncmp(dataq->type, "*USRDFN", 7) != 0) || (fldlen == 0)) 
QRCVDTAQ(qname->name, qname->library, fldlen, datag, waittime, \ 
order, keylen, key, senderid,""); 
} /* End dequeue Subroutine */ 
[ORK RK KK KKK KK IA A A A RR A A A A A I I 
[RRRRKKEKER ERK Set a timer and dequeue next entry ******/ 
void settimer (unsigned short *expctid, 
char *process, 
gentry *dataq, 
usrspace *qname, 
char *commhandle) 
{ 
timerparms timer; 
disableparms disable; 
int length; 
char key[6]; 


timer.interval = 20000; /* set timer for 20 seconds */ 
timer.establishcount = 1; /* set establish count to 1 */ 
timer.keylength = 3; /* key value */ 
strncpy(timer.keyvalue, "TGT", 3); /* set key value / 
timer.operation = 1; /* set a timer */ 


/* Call QOLTIMER */ 
QOLTIMER (&(timer.retcode 
timer.handlein, 


) (timer.reason), timer.handleout, \ 
( 

& (timer.interval) 
h 


por 
char *)qname, &(timer.operation), \ 
, &(timer.establishcount), \ 

), timer.keyvalue, timer.userdata) ; 
| (timer.reason != 0)) 


& (timer.keylengt 
if ((timer.retcode != 0) 
{ 
printf("%s timer failed while being set.\n", process); 
printf ("Return code = %d\n", timer.retcode) ; 
printf ("Reason code = %d\n\n", timer.reason); 


[RRS tae Dequeue an entry -—------- Ae 
strncpy (key, "TGT", 3); 
length = 3; 
dequeue (length, key, dataq, qname) ; 
[RR RSA Cancel timer = ---—- REAL 
if (dataq->msgid != OxFOF4) 
{ 
strncpy(timer.handlein, timer.handleout, 8); 
timer.operation = 2; /* Cancel one timer */ 
QOLTIMER (&(timer.retcode), &(timer.reason), timer.handleout, \ 
timer.handlein, (char *)qname, &(timer.operation), \ 
&(timer.interval), &(timer.establishcount),\ 
&(timer.keylength), timer.keyvalue, timer.userdata) ; 
if ((timer.retcode != 0) || (timer.reason != 0)) 
{ 
printf("%s timer failed while being canceled\n", process); 
printf ("Return code = %d\n", timer.retcode) ; 
printf ("Reason code = %d\n\n", timer.reason); 
} 
} 
if (dataq->msgid != *expctid) 
{ 
printf ("A %.4X message ID was received instead of %.4xX\n",\ 
dataq->msgid, *expctid); 
printf ("Ss completion message was not received\n", process) ; 
*expctid = dataq->msgid; 
} 
} /* End settimer Subroutine */ 
[KKK KR KKK KKK KK IK IK IA IA I I A I I / 
/** x25lind: Read a record into buf and return length At 
void x25lind (qlindparms *qlind, char *linename) 
{ 
register int counter; 
for (counter=0; counter<256; counter+t+) 
qlind->userbuffer [counter] =0; 


qlind->format = 0x01; 
QOLQLIND (&(qlind->retcode), &(qlind->reason), &(qlind->nbytes),\ 


} 


qlind->userbuffer, linename, &(qlind->format) ); 
/* End x25lind Subroutine */ 


[OR KK KKK KK KKK KK IR AR IA AA I I A I A A He / 


[** 


putdata: Read a record into buf and return length xx / 


void putdata (char *buf, 


{ 


int dtalen, 
FILE *fptr) 


int i; 


} 


for (i = 0; i < dtalen; i++) 
fwrite(buf + i, 1, 1, fptr); 
/* End putdata Subroutine */ 


Target application program listing references 


The following reference numbers and explanations correspond to the reference numbers in the target application's program listing. 


(1) 


(2) 


(3) 


(4) 


(5) 


(6) 


(7) 


(8) 


(9) 


Call the C library routines fopen() and signal() to open the target file and set up a signal handler to process OS/400 
exceptions, respectively. If an exception situation is encountered, the handler() will be called to perform clean-up in order for 
the program to end. 


Call the QOLELINK API to enable the line description using the line name and communications handle passed as input 
parameters to this program. 


Call the QOLTIMER API to time the completion of the enable link operation. If the timer expires before the enable-complete 
message is posted on the this program's data queue, then this program will end. 


Call the QUSPTRUS API to obtain a pointer to the beginning of the output buffer user space. The output buffer will be used 
to construct a filter list for the call to the QOLSETF API. 


Call the QOLRECV API to receive inbound data after reading an incoming data message that was posted on the program's 
data queue by the user-defined communications support. Since these programs are operating using the communications 
services of X.25, the first data unit the target program should see is a X'B201' operation signalling an incoming call was 
received. 


Call the QOLSEND API with a X'B400' operation to accept the incoming X.25 call. A connection is now established between 
the source and target application programs. 


The target program will now set a timer by calling the QOLTIMER API and wait for incoming data. If the timer expires 
before any incoming data is received, then this program will call the QOLDLINK API, and end. 


This is the main receive loop for the target program. When data is received from the source program, it will be written to the 
target file opened during the initialization of this program. The loop will process until a message other than incoming-data 
entry is read from the program's data queue. 


Call the QOLSEND API with a X'BO01' operation to locally close the connection. 


(10) Receives a X'B101' operation from the user-defined communications support. This is a local confirmation of X'B100' 


operation. 


(11) Call the QOLDLINK API to disable the link previously enabled and end. 


Includes for Source and Target Programs 


The following three includes are used by both the preceding source and target programs. They are not in an OS/400 library. 


[OK KK KK KKK KK I IA A A A A RA AA A AA A A A I I Hk / 


[KK RK KK KK KKK KK AA IA A A A A AA IA IR AA A A I A I I I / 


Include Name: Header *f 
*/ 

*/ 

Function: */ 
Type define and declare the structures used to interface #7 
to the user-defined communications APIs. These structures */ 
are used by both the source and target application. */ 
*/ 

*f 

LANGUAGE: ILE C for 0OS/400 */ 
*/ 


/* APIs USED: QOLDLINK, QOLELINK, QOLSEND, QOLRECV, QOLSETF, */ 
ae QOLTIMER, QUSPTRUS, QORCVDTAQ, QOCLRDTAQ, QOLOQLIND a) 
i& */ 


[KK RK KKK KK KK IK A A A A A A AA IA IA A I A I A I I / 


[BKK RK KK KKK KK KK AK IA A A RR A AIA AA A A I A I I 


FILE *screen; 
FILE *rptr; 
FILE *fptr; 


#include <qoldlink.h> 
#include <qolelink.h> 
#include <qolsend.h> 
#include <qolrecv.h> 
#include <qolsetf.h> 
#include <qoltimer.h> 
#include <qusptrus.h> 
#include <qrcvdtagq.h> 
#include <qclrdtaq.h> 
#include <qolqlind.h> 


[KKK KK KK KKK KK Typedef Declarations TK RK KK KK / 


typedef struct usrspace 
{ 
char name[10]; 
char library[10]; 
} usrspace; 


typedef struct enableparms /* Enable parameters */ 
{ 
int retcode, /* Output */ 
reason, /* Output */ 
tdusize, /* Output */ 
numunits, /* Output */ 
maxdtalan, /* Output */ 
maxdtax25, /* Input ia 
keylength; /* Input */ 
char keyvalue[256], /* Input */ 
linename[10]; /* Input */ 


} enableparms; 


typedef struct disableparms /* Disable parameters */ 
{ 
int retcode, /* Output */ 
reason; /* Output */ 
char vary; /* Input */ 


} disableparms; 


typedef struct setfparms /* Set Filters parameters */ 
{ 
int retcode, /* Output */ 
reason, /* Output */ 
erroffset; /* Output */ 


} setfparms; 


typedef _Packed struct hdrparms /* Filter header */ 
{ 
char function; 
char type; 
unsigned short number; 
unsigned short length; 
char filters[1]; 
} hdrparms; 


typedef _Packed struct x25filter /* X.25 filter */ 
{ 


char pidlength; 
char pid; 

char dtelength; 
char dte[12]; 
char flags; 

} x25filter; 


typedef struct sendparms /* Send parameters */ 
{ 
espec errorspecific; /* Output */ 
int retcode, /* Output */ 
reason, /* Output */ 
newpcep, /* Output */ 
ucep, /* Input */ 
pcep, /* Input af 
numdtaelmnts; /* Input */ 
unsigned short operation; /* Input */ 
} sendparms; 
typedef struct recvparms /* Receive parameters */ 
{ 
espec errorspecific; /* Output */ 
int retcode, /* Output */ 
reason, /* Output */ 
newpcep, /* Output */ 
ucep, /* Output */ 
pcep, /* Output xf 
numdtaunits; /* Output ed 
char dataavail; /* Output */ 
unsigned short operation; /* Output */ 
} recvparms; 
typedef struct timerparms /* Timer parameters */ 
{ 
int retcode, /* Output */ 
reason, /* Output */ 
interval, /* Input */ 
establishcount, /* Input */ 
keylength; /* Input Ewe 
char handleout[8], /* Output */ 
handlein[8], /* Input */ 
operation, /* Input */ 
keyvalue[256], /* Input */ 
userdata[60]; /* Input */ 
} timerparms; 
typedef struct especout 
{ 
char hwecode [8]; 
char timestamp[16]; 
char elogid[8]; 
char fail; 
char zerocodes; 
char qsysopr; 
char cause[2]; 
char diagnostic[2]; 
char erroffset[6]; 
} especout; 
typedef struct gqlindparms /* Query line parameters 
{ 
int retcode, /* Output */ 
reason, /* Output */ 
nbytes; /* Output */ 


char userbuffer[256]; 
char format; 


ae 


} qlindparms; 


typedef _Packed union content /* Queue support parameters */ 
{ 
_Packed struct other 
{ 
char commhandle[10]; 
char reserved[58]; 
} other; 
_Packed struct enable 
{ 
char commhandle[10]; 
char status; 
char reserved[57]; 
} enable; 
_Packed struct timer 
{ 
char timerhandle[8]; 
char userdata[60]; 
} timer; 
} content; 


typedef _Packed struct gentry /* Queue parameters */ 
{ 
char type[10]; 
unsigned short msgid; 
content message; 
char key[256]; 
} gentry; 


The following typedef include has new type declarations used by both source and target programs. 


[BORK RK KK KK KKK IK IA A A A A AA AA A AA A A I A I I / 
[KK RK KK KK KK KK A A A A A RA AA IA AA A A I A I / 


/* Include Name: Typedef */ 
[* *f 
/* Function: */ 
/* Define the buffer spaces used to pass the data to the */ 
/* APIs. A 
fF *f 
/* *] 
/* LANGUAGE: ILE C for OS/400 */ 
ps #/ 


[KK RK KK KKK KKK AK A IA A A A A AA IA AA A A A I I / 
[KK RK KK KKK KKK IK AA IA IA A RR A AA IA A A A I A I I I 


/*These definitions and C library #include files are either global, or 
are used by multiple modules in the Open FM API driver.*/ 


#include <stdio.h> 
#include <stdlib.h> 
#include <signal.h> 
#include <xxcvt.h> 
#include <string.h> 
#include <ctype.h> 
#include <recio.h> 


typedef struct queuein 
{ 
char library[10]; 
char name[10]; 
char option; 
} queuein; 


typedef struct namelib 


{ 
char library[10]; 


char name[10]; 
} namelib; 


typedef _Packed struct formatl 
{ 
char type; 
char reservedl; 
unsigned short logchanid; 
unsigned short sendpacksize; 
unsigned short sendwindsize; 
unsigned short recvpacksize; 
unsigned short recvwindsize; 
char reserved2[7]; 
char dtelength; 
char dte[16]; 
char reserved3[8]; 
char dbit; 
char reserved4[7]; 
char cug; 
char cugid; 
char reverse; 
char fast; 
char faclength; 
char facilities[109]; 
char reserved5 [48]; 
unsigned short calllength; 
char callud[128]; 
char reserved6[128]; 
unsigned char misc[4]; 
unsigned int maxasmsize; 
unsigned short autoflow; 

} formatl; 


typedef _Packed struct format2 
{ 
unsigned short type; 
char cause; 
char diagnostic; 
char reserved[4]; 
char faclength; 
char facilities[109]; 
char reserved2 [48]; 
unsigned short length; 
char userdata[128]; 
} format2; 


typedef _Packed struct desc 


{ 
unsigned short length; 


char more; /*These 


char qualified; 
char interrupt; 
char dbit; 

char reserved[26]; 
} desc; 


typedef _Packed struct llcheader 
{ 
unsigned short headerlength; 
char macaddr[6]; 
char dsap; 
char ssap; 
char priority; 
char priorctl; 
unsigned short routlen; 
unsigned short userdtalen; 
char data[1]; 


/* control flags */ 


4 char's are only used for X.25.*/ 


typedef _Packed struct espec 


} llcheader; 


{ 


char reserved[ 


2]; 


unsigned int hwecode; 


unsigned int timestamphi; 
unsigned int timestamplo; 


unsigned int e 
char reserved2 
char flags; 
char cause; 
char diagnosti 
char reserved3 


unsigned int erroroffset; 


char reserved4 
} espec; 


logid; 
[10]; 


Cr 


, 


[4]; 


typedef struct tableentry 


[RKKKKKK 
[RKKKKKK 


{ 
char handle[1 
char type; 
char inbuff[2 
char indesc[2 
char outbuff[ 
char outdesc[ 


unsigned int totaldusize; 
struct tableentry *next; 


} tableentry; 


Ol; 


Ol; 
Ol; 
20]; 
20]; 


Data structure for X.25 line 
descriptions as returned by QOLQLIND. ******/ 


typedef struct x25info 


{ 
char addrilen; 
char addr[9]; 
char addrtype; 
char insert; 
char modulus; 
char dtedce; 
unsigned short 
unsigned short 
unsigned short 
unsigned short 
char windowsen 
char windowrec 
unsigned short 
char lcinfo[4] 

} x25info; 


maxsend; 
maxrecv; 
defsend; 
defrecv; 
d; 
Vi 
numlc; 


, 


typedef struct querydata 


{ 
char header [12 
x25info x25dat 
} querydata; 


KK KK Ke / 


li /* line header info */ 


a; 


/* preliminary data */ 


[KK RK KK KK KKK IK IA A A A A RA A AA A A A I A I I / 


[KK RK KK KK KKK AK AA IA A A A A A IA A IA A I A I A I I / 


/* 


Include Name: 


Function: 


This include brings in procedures to convert hexadecimal 
to integer values and vice versa. 


LANGUAGE: ILE C for OS/400 


Hexconv 


ey 
*/ 


i ws 
[KK RK KK KK KKK KK AA IA A A A A AA AA IA IA IA A I A I I I He / 
[KK RK KK KKK KK KK A IA A A A RA AA AA A A A I I / 


#include <stdio.h> 
unsigned int hextoint(char *); 


char *inttohex(decimal,hex) /*Converts a 4-byte integer into a 

string of 2 uppercase hex characters.*/ 
unsigned int decimal; 
char *hex; 


{ 
sprintf (hex,"%$.2X",decimal) ; 
return (hex) ; 


} 


unsigned int hextoint (hex) /*Converts a string containing hex 
digits into a 4-byte integer. Ef 
char *hex; 


{ 


int decimal; 


sscanf (hex, "Sx", &decimal); 
return (decimal) ; 


Using the Control Device (QTACTLDV) API 


This example shows how the QTACTLDV (Control Device) API could be used to send a diagnostic command to a tape device. 


/* Usage example for QTACTLDV API */ 
Vi *y 
ees Hef 


#include <string.h> 
#include <stdio.h> 
#include <qtactldv.h> 
#include <qusec.h> 


[KOK KKK KK KK RR IR I I I I A A A A A AA AA A A I I I I / 


/* Typedef structure for QTACTLDV *«/ 
[KOK KKK KK KR IR IA I A I A A A A A A AA A A AI A I I / 
typedef struct { /* QTACTLDV command data */ 
Qta_CTLDO100_t data; f* command data */ 
char cmd_str[6]; /* command string */ 


} cmd_struct; 


[KOK KKK KK KR KR IA I A A I A A A A A A AA A A I I I I / 


/* Typedef structure for Error code Kf 
[KOK RK KK KK RA IA I A I I A A A AA A AA A A A I I I I / 
typedef struct { /* Error code structure */ 
Qus_EC_t Edata; /* Error code data */ 
/* CPF67C8 excp data xf 

char dev_nam[10]; /* Device name */ 
char reason_cd[3]; /* Reason code */ 
char resvl [3]; /* Reserved sae 


} EC_struct; 


ete ee ee a ee ee a a i a a a ee ee a ee f 


/* Constants */ 
[KOK KKK KK KR A AA A A A I A A A A A AA AA A A I A I I / 


#define SNDRSNS "\x03\x00\x00\x00\x12\x00" /* Request sense aw 


/* command string * / 
#define SNDDIAG "\x1D\x04\x00\x00\x00\x00" /* Send diagnostic wy 
/* command string * / 


main(int argc,char *argv[]) 


{ 


[KOK KK KK KK RR IA I A I I A A A A A AA AA A A I I I I / 


[x * / 
/* START OF MAINLINE */ 
pe Ke. 


[KOK KKK KK KR A IR I A I I A A A A A AA AA A I I I I / 


ete ee ee ee ee ee ee ee ee a a a a a a ee f 


/* Variables for QTACTLDV ols 


[KOK KK KK KK RR IA I I I I A A A A A AA AA A A I I I I / 


char device[10]; /* device name */ 
char send_buff[256]; /* send buffer */ 
int send_buff_len; /* length of send buffer */ 
char recv_buff [256]; /* receive buffer * / 
int recv_buff_len; /* length of recv buffer */ 
int cmd_data_len; /* length of command data */ 
int is /* counter variable af 
EC_struct EC; /* error code structure */ 
cmd_struct Cmd; /* struct for QTACTLDV */ 
memcpy (device,argv[1],10); /* copy device name * / 


[KOK KKK KK KK RR IA I I A I A A A A A AA AA A A I I I I / 


/* OPEN connection ae 
[KOK KK KK KK RR IA I I I A A A A AA IA AA AA A A I A I I / 
send_buff_len = 0; /* no send buffer mf, 
recv_buff_len = 0; /* no receive buffer */ 
cmd_data_len = 0; /* no command data mf 
EC.Edata.Bytes_Provided = 32; /* No exceptions wf 
QTACTLDV (device, /* device name *f 
FUNOPEN, /* requested function * ff 
send_buff, /* send buffer */ 
send_buff_len, /* length of send buffer */ 
recv_buff, /* receive buffer */ 
recv_buff_len, /* length of receive buffer */ 
CTLDO100, /* command format ay: 
&Cmd, /* command data Pol: 
cmd_data_len, /* length of command data *f 
&EC) ; /* Error Code */ 
if (EC.Edata.Bytes_Available>0) /* If there was an error */ 
{ 
/* Handle the error ey 


} 


et ee ee ee ee ee ee i a a a a ee a ee f 


/* Send Diagnostic command vA 
[KOK KKK KK KR KR IA I I I A A A A A A AA AA A A I I I I / 
send_buff_len = 0; /* no send buffer */ 
recv_buff_len = 0; /* no recv buffer xf 
cmd_data_len = sizeof (Cmd) ; /* size of command struct */ 
EC.Edata.Bytes_Provided = 32; /* No exceptions */ 
Cmd.data.Data_transfer_direction = XFRNONE; /* No data transfer */ 
Cmd.data.Requested_transfer_length = 0; /* 0 transfer length */ 
Cmd.data.Ignore_length_errors = RPTLERR; /* report length errs */ 
Cmd.data.Command_timeout = 600; /* 10 minute timeout */ 
Cmd.data.Type_of_command = CMDSCSI; /* SCSI command */ 
Cmd.data.Offset_to_command_string = 32; /* offset 32 */ 


Cmd.data.Length_of_command_string = 6; /* 6 byte command * / 


Cmd.data.Reserved1=0; /* reserved ay 


memcpy (&Cmd.cmd_str, SNDDIAG, 6); /* command string */ 
QTACTLDV (device, /* device name */ 
FUNCMD, /* requested function */ 
send_buff, /* send buffer */ 
send_buff_len, /* length of send buffer */ 
recv_buff, /* receive buffer */ 
recv_buff_len, /* length of receive buffer */ 
CTLDO100, /* command format ae 
&Cmd, /* command data ef 
cmd_data_len, /* length of command data ef 
&EC) ; /* Error code */ 
if (EC.Edata.Bytes_Available>0) /* If there was an error */ 
{ 
/* See what message was returned ay 
if (strncmp (EC.Edata.Exception_Id, "CPF67C8",7)==0) /* Command 


failed msg */ 


[ROKK RK KK KK RK KKK I A A A A AA A A A A A A A I I 


/* Check the data returned with CPF67C8 */ 


[KK RK KK KK KK I I A A A A AR A A A A A A I I / 


if (strncmp(EC.reason_cd,"\x02\xC0O", 2) == 0) /* Device detected 
error */ 
{ 
/* Check the SCSI completion status */ 
if (EC.reason_cd[2]=='\x02") /* Check condition status */ 


{ 


[BOR KR KK KK KR A IA I A A I A A A A A A 


/* Send Request Sense command ig 
[BOR KKK RK KKK KK KR IA I I I I A A A A A A A A I I / 
send_buff_len = 0; /* no send buffer */ 
recv_buff_len = 18; /* length of recv buffer af 
cmd_data_len = sizeof (Cmd); /* size of command struct */ 
Cmd.data.Data_transfer_direction = XFRRECV; /* receive */ 
Cmd.data.Requested_transfer_length = 18; /* 18 bytes mf 
Cmd.data.Ignore_length_errors = IGNLERR; /* ignore length 
errors */ 
Cmd.data.Command_timeout = 60; /* 60 sec timeout */ 
Cmd.data.Type_of_command = CMDSCSI; /* SCSI command mf 
Cmd.data.Offset_to_command_string = 32; /* offset 32 * / 
Cmd.data.Length_of_command_string = 6; /* 6 byte cmd * / 
Cmd.data.Reserved1=0; /* reserved ers 
memcpy (&Cmd.cmd_str, SNDRSNS, 6); /* command string */ 
EC.Edata.Bytes_Provided = 32; /* No exceptions */ 
QTACTLDV (device, /* device name */ 
FUNCMD, /* requested function */ 
send_buff, /* send buffer */ 
send_buff_len, /* length of send buffer */ 
recv_buff, /* receive buffer */ 
recv_buff_len, /* length of receive buffer */ 
CTLDO100, /* command format */ 
&Cmd, /* command data */ 
cmd_data_len, /* length of command data *f 
&EC) ; /* Error code */ 
if (EC.Edata.Bytes_Available>0) /* If there was an error */ 
{ 
/* Handle error on request sense command */ 
} 
else 


{ 


/* Parse the request sense data to determine what action */ 


} 


el 
{ 


} 
} 
else 
{ 

/* 
} 


/* to take. 


else if (EC.reason_cd[2]=='\x08') /* Busy status 
/* Try the command again later 
else /* Unexpected completion status 


/* Send error message for unexpected completion status 


else if (strncmp(EC.reason_cd,"\x02\xC1\x00", 3) == 0) 
/* Selection timeout 


{ 

/* Send message that device might be powered off 
} 
/* Add else if for the other reason codes here 
else 


{ 


/* Send error message for unexpected reason code 


} 


se 


/* Handle other messages 


No error 


ef 


ad 
ape 
aA 
af 


Pals 


*f 


ef 


ad 


aA 


fs 
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/* CLOSE connection zd 
[KOK KR KK KK KR AA I A I I A A A A A AA AA A A A I I / 
send_buff_len = 0; /* no send buffer */ 
recv_buff_len = 0; /* no receive buffer */ 
cmd_data_len = 0; /* no command data */ 
EC.Edata.Bytes_Provided = 32; /* No exceptions */ 
QTACTLDV (device, /* device name ef 
FUNCLOS, /* requested function * / 
send_buff, /* send buffer */ 
send_buff_len, /* length of send buffer */ 
recv_buff, /* receive buffer */ 
recv_buff_len, /* length of receive buffer */ 
CTLDO100, /* command format aA 
&Cmd, /* command data Af: 
cmd_data_len, /* length of command data aA 
&EC.Edata); /* Error code ey 
if (EC.Edata.Bytes_Available>0) /* If there was an error */ 
{ 
/* Handle the error */ 


} 
} 


Using a Data Queue 


The following examples explain three methods to process data queue files. 

Example 1: Waiting up to 2 Hours to Receive Data from Data Queue 

In the following example, program B specifies to wait up to 2 hours (7200 seconds) to receive an entry from the data queue. Program 
A sends an entry to data queue DTAQ1 in library QGPL. If program A sends an entry within 2 hours, program B receives the entries 
from this data queue. Processing begins immediately. If 2 hours elapse without program A sending an entry, program B processes the 
time-out condition because the field length returned is 0. Program B continues receiving entries until this time-out condition occurs. 
The programs are written in CL; however, either program could be written in any high-level language. 


The data queue is created with the following command: 


CRIDTAQ DTAQ(QGPL/DTAQ1) MAXLEN (80) 
In this example, all data queue entries are 80 bytes long. 


In program A, the following statements relate to the data queue: 


PGM 
DCL &FLDLEN *DEC LEN(5 0) VALUE(80) 
DCL &FIELD *CHAR  LEN(80) 


. (determine data to be sent to the queue) 


CALL QSNDDTAQ PARM(DTAQ1 QOGPL &FLDLEN &FIELD) 


In program B, the following statements relate to the data queue: 


PGM 

DCL &FLDLEN *DEC LEN(5 0) VALUE(80) 

DCL &FIELD *CHAR  LEN(80) 

DCL é&WAIT *DEC LEN(5 0) VALUE(7200) /* 2 hours */ 


LOOP: CALL QRCVDTAQ PARM(DTAQ1 
QGPL &FLDLEN &FIELD &WAIT) 
IF (&FLDLEN *NE 0) DO /* Entry received */ 


(process data from data queue) 


GOTO LOOP /* Get next entry from data queue */ 
ENDDO 


(no entries received for 
2 hours; process time-out condition) 
Example 2: Waiting for Input from a Display File and an ICF File 


The following example is different from the usual use of data queues because there is only one job. The data queue serves as a 
communications object within the job rather than between two jobs. 


JobA 


ICF Application Display 
File |—| Program File 
at 


In this example, a program is waiting for input from a display file and an ICF file. Instead of alternately waiting for one and then the 
other, a data queue is used to allow the program to wait on one object (the data queue). The program calls QRCVDTAQ and waits for 
an entry to be placed on the data queue that was specified on the display file and the ICF file. Both files specify the same data queue. 
Two types of entries are put on the queue by display data management and ICF data management support when the data is available 
from either file. ICF file entries start with *ICFF and display file entries start with *DSPF. 


The display file or ICF file entry that is put on the data queue is 80 characters in length and contains the field attributes described in 
the following table. Therefore, the data queue that is specified using the CRTDSPF, CHGDSPF, OVRDSPF, CRTICFF, CHGICFF, 
and OVRICFF commands must have a length of at least 80 characters. 


Position (and Data Type) 


1 through 10 (character) 


Description 


The type of file that placed the entry on the data queue. This field will have one of two 
values: 


*ICFF for ICF file 
*DSPF for display file 
If the job receiving the data from the data queue has only one display file or one ICF file 


open, then this is the only field needed to determine what type of entry has been received 
from the data queue. 


11 through 12 (binary) The unique identifier for the file. The value of the identifier is the same as the value in the 
open feedback area for the file. This field should be used by the program receiving the 
entry from the data queue only if there is more than one file with the same name placing 


entries on the data queue. 


The name of the display file or ICF file. This is the name of the file actually opened, after 
all overrides have been processed, and is the same as the file name found in the open 
feedback area for the file. This field should be used by the program receiving the entry 
from the data queue only if there is more than one display file or ICF file that is placing 
entries on the data queue. 


13 through 22 (character) 


23 through 32 (character) The library where the file is located. This is the name of the library, after all overrides have 
been processed, and is the same as the library name found in the open feedback area for the 
file. This field should be used by the program receiving the entry from the data queue only 
if there is more than one display file or ICF file that is placing entries on the data queue. 


33 through 42 (character) 


The program device name, after all overrides have been processed. This name is the same 
as that found in the program device definition list of the open feedback area. For file type 
*DSPF, this is the name of the display device where the command or Enter key was 
pressed. For file type *ICFF, this is the name of the program device where data is 
available. This field should be used by the program receiving the entry from the data queue 
only if the file that placed the entry on the data queue has more than one device or session 
invited prior to receiving the data queue entry. 


43 through 80 (character) Reserved. 


The following example shows coding logic that the application program previously described might use: 


OPEN DSPFILE 


/* Open the Display file. DTAQ parameter specified on*/ 
/* CRIDSPF, CHGDSPF, or OVRDSPF for the file. ifs 
OPEN ICFFILE 
/* Open the ICF file. DTAQ parameter specified on */ 
/* CRTICFF, CHGICFF, or OVRICFF for the file. */ 
DO 
WRITE DSPFILE 
/* Write with Invite for the Display file Rp 
WRITE ICFFILE 
/* Write with Invite for the ICF file Py 
CALL QRCVDTAQ 
/* Receive an entry from the data queue specified bi 
/* on the DTAQ parameters for the files. Entries ty 
/* are placed on the data queue when the data is */ 
/* available from any invited device or session * / 
/* on either file. */ 
/* After the entry is received, determine which file */ 
/* has data available, read the data, process it, Ref 
/* invite the file again and return to process the yA 
/* next entry on the data queue. KY 
IF 'ENTRY TYPE' FIELD = '*DSPF ' THEN 
/* Entry is from display */ 
DO /* file. Since this entry*/ 
/* does not contain the */ 
/* data received, the data*/ 
/* must be read from the */ 
/* file before it can be */ 
READ DATA FROM DISPLAY FILE /* processed. Ff: 
PROCESS INPUT DATA FROM DISPLAY FILE 
WRITE TO DISPLAY FILE /* Write with Invite ney 
END 
ELSE /* Entry is from ICF */ 
/* file. Since this entry*/ 
/* does not contain the */ 
/* data received, the data*/ 
/* must be read from the */ 
/* file before it can be */ 
/* processed. */ 
READ DATA FROM ICF FILE 
PROCESS INPUT DATA FROM ICF FILE 
WRITE TO ICF FILE /* Write with Invite a1 
LOOP BACK TO RECEIVE ENTRY FROM DATA QUEUE 
END 


Example 3: Waiting for Input from a Display File and a Data Queue 


In the following example, the program in Job B is waiting for input from a display file that it is using and for input to arrive on the 
data queue from Job A. Instead of alternately waiting for the display file and then the data queue, the program waits for one object, 
the data queue. 


JobA Jobe 


Batch Job 
Placing User 


Interactive Job 


Using Display 

File and Receiving 
Entries from the 
Data Queue 


Data 


Entries on Queue 


on the Data 
Queue 


Display File 


The program calls QRCVDTAQ and waits for an entry to be placed on the data queue that was specified on the display file. Job A is 
also placing entries on the same data queue. There are two types of entries put on this queue, the display file entry and the 
user-defined entry. The display file entry is placed on the data queue by display data management when data is available from the 
display file. The user-defined entry is placing on the data queue by Job A. 

The structure of the display file entry is described in the previous example. 


The structure of the entry placed on the queue by Job A is defined by the application programmer. 


The following example shows coding logic that the application program in Job B might use: 


OPEN DSPFILE 
/* Open the Display file. DTAQ parameter specified on*/ 
/* CRIDSPF, CHGDSPF, or OVRDSPF for the file. */ 


DO 
WRITE DSPFILE /* Write with Invite for the Display file * / 


CALL QRCVDTAO 


/* Receive an entry from the data queue specified */ 
/* on the DTAQ parameter for the file. Entries a 
/* are placed on the data queue either by Job A or */ 
/* by display data management when data is Lad 
/* available from any invited device on the display */ 
/* file. */ 


/* After the entry is received, determine what type */ 
/* of entry it is, process it, and return to receive */ 


/* the next entry on the data queue. */ 

IF 'ENTRY TYPE' FIELD = '*DSPF ' THEN 
/* Entry is from display */ 
DO /* file. Since this entry*/ 
/* does not contain the */ 


/* data received, the data*/ 
/* must be read from the */ 
/* file before it can be */ 
READ DATA FROM DISPLAY FILE /* processed. */ 
PROCESS INPUT DATA FROM DISPLAY FILE 
WRITE TO DISPLAY FILE 


/* Write with Invite Ewd 


END 

ELSE /* Entry is from Job A. */ 
/* This entry contains #Y. 
/* the data from Job A, */ 
/* so no read is required*/ 
/* before processing the */ 
/* data. *f 

PROCESS DATA QUEUE ENTRY FROM JOB A 
LOOP BACK TO RECEIVE ENTRY FROM DATA QUEUE 


END 


Using Environment Variables 


This program displays the value of an environment variable and then sets the environment variable to a new value. 
Use the Create C Module (CRTCMOD) and the Create Program (CRTPGM) commands to create this program. 


Call this program with one parameter to display the environment variable specified by that parameter. Call this program with two 
parameters to set the environment variable specified by the first parameter to the value specified by the second parameter. 
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leg aye 
/* FUNCTION: Display the value of an environment variable and */ 
/* then set the environment variable to a new value. 7 
/* */ 
/* LANGUAGE: ILE C for 0OS/400 */ 
/* */ 
/* APIs USED: getenv(), putenv() */ 
/* */ 
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#include <stdio.h> 
#include <stdlib.h> 
#include <errno.h> 
#include <string.h> 


#define BUFLEN 1024 


int main(int argc, char *argv[]) 


{ 


int num=0; /* counter ef 
int rec} /* API return code ae 
int desl gs+ Hie /* lengths of the two parameters */ 
char *envvar=NULL; /* pointer to an environment variable*/ 
char **envvaridx=NULL; /* pointer to an envvar pointer ay 


char envstring[BUFLEN]; 
/* buffer to construct putenv request*/ 


/* Show a small usage message. af 
if ((argce != 2) && (argc != 3)) { 
printf ("Usage: %s <ENV_VAR> <new_value>\n OR \n" 
"Usage: %S <ENV_VAR>\n", argv[0], argv[0]); 

printf("Sets an environment variable to a user requested\n" 

"value\n" 

"OR\nDisplays the value of a single environment variable\n"); 
exit (1); 


/* Called just to display the environment variables. */ 
envvar = getenv(argv[1]); 
if (envvar == NULL) { 
printf("No environment variable %s set\n", 
argv[1]); 
} 
else { 
printf ("Environment variable: %s\n", envvar); 
} 
return 0; 


} 
/* ELSE, called to set an environment variable. aA 


/* Check the size of the parameters and construct a string of */ 
/* the form "VAR=string" which is valid input to putenv. */ 
11 = strlen(argv[1]); 
12 = strlen(argv[2]); 
if (11+12+2 >= BUFLEN) { 
printf ("Only 1024 characters total allowed for this test\n"); 
exit (1); 

} 
memcpy(envstring, argv[1], 11); 
envstring[1l1] = '='; 
memcpy (&envstring[11+1], argv[2], 12); 
envstring[11+12+1]="'\0'; 


/* Now that the string is built, let's see if the environment */ 


/* variable was already set. * 
envvar = getenv(argv[1]); 
if (envvar == NULL) { 


printf ("Setting NEW environment variable %s\n", 
envstring) ; 
} 
else { 
printf ("Resetting OLD environment variable from: %s\n to %s\n", 
envvar, envstring) ; 


} 


/* Now actually set the environment variable. */ 
re = putenv(envstring) ; 
if (re < 0) { 

printf ("putenv failed, errno = %d\n", errno); 


return —-1; 
} 
printf ("Environment variable set\n"); 
return 0; 


Saving and Restoring System-Level Environment 
Variables 


The following two-part example illustrates how to save the current set of system-level environment variables and restore them later. 


Saving System-Level Environment Variables 


This program stores the system-level environment variables and the associated CCSIDs in a file for restoring later. 
Use the Create C Module (CRTCMOD) and the Create Program (CRTPGM) commands to create this program. 


Call this program with one parameter (the file to store the variable list and the CCSIDs). 
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TK KK KI A A A A A I A A A A A A A I / 
Fe KKK A A A A A A A A A A A A A A I / 


/* */ 
/* FUNCTION: Save the system-level environment variable list */ 
pa and the CCSIDs in a file 7] 
aa tif 
/* LANGUAGE: ILE C for OS/400 */ 
1% */ 
/* APIs USED: Qp0zGetAllSysEnv() avd 
LF *y 


[RKKKKKK 
[RKKKKKK 


#include 
#include 
#include 
#include 
#include 
#include 
#include 


int main 


{ 


int 
int 
char 
int 


if(a 
{ 
pr 
pr 
re 


} 


sl = 
sc = 
list 
ccsi 


[EGG 
[XE 
[EO 
fd = 
if(f 
{ 

pr 

re 


} 


re = 


if(r 
{ 
/* 
/* 


if 
{ 
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<fcntl.h> 
<stdio.h> 
<unistd.h> 
<sys/stat.h> 
<stdlib.h> 
<errno.h> 
<qp0z1170.h> 


(int argc, char *argv[]) 


fd, bw, rc; 

listBufSize, ccsidBufSize, *ccsidBuf; 
*listBuf; 

numvar, sl, sc; 


rgc != 2) 


intf("Usage: call %s <filename>\n",argv[0]); 
intf("Example: call %s '/tmp/sev'\n",argv[0]); 
turn —-1; 


listBufSize = 1000; 

ccsidBufSize = 1000; 
Buf = (char *)malloc(listBufSize)j; 
dBuf = (int *)malloc(ccsidBufSize) ; 


reate a file of specified name */ 

f it exists, it is cleared out */ 

pened for writing ia 
open(argv[1], O_CREAT | O_WRONLY | O_TRUNC, S_IRWXU); 
== -1) 

intf("open() failed. errno = %d\n", errno); 

turn —-1; 


Qp0zGetAllSysEnv(listBuf, &listBufSize, ccsidBuf, 
&éccsidBufSize, NULL); 


c != 0) 
If there are no variables to save, write a */ 
zero into the file and return success ey. 
(cc == ENOENT) 
numvar = 0; 


bw = write(fd, &numvar, sizeof(int)); 
close(fd); 
printf("No system-level environment variables to save"); 


return 0; 


} 


if(rc != ENOSPC) 

{ 
printf("Error using Qp0zGetAllSysEnv(), errno = %d\n", rc); 
return -1; 


} 


/* rc = ENOSPC. size of buffer is not enough */ 
/* change buffer size and try again */ 


/* If listBuf is not large enough, */ 
/* allocate more space nA 
if (listBufSize > sl) 
{ 
listBuf = (char *)realloc(listBuf, listBufSize); 
} 


/* If ccsidBuf is too small, allocate */ 
/* more space */ 
if (ccsidBufSize > sc) 
{ 
ccsidBuf = (int *)realloc(ccsidBuf, ccsidBufSize); 


} 


re = Qp0zGetAllSysEnv(listBuf, &listBufSize, 
ccsidBuf, &ccsidBufSize, NULL); 
if(re != 0) 
{ 
printf("Error using Qp0zGetAllSysEnv(), errno = %d\n", rc); 
return -1; 


} 


/* Write the contents of the buffer into the file */ 


/* First write the total number of ccsid values *f 
/* This is the total number of variables 4 
numvar = ccsidBufSize/sizeof (int); 


bw = write(fd, &numvar, sizeof(int)); 
if (bw == -1) 
{ 
printf ("write() of total number of ccsids failed. errno = %d\n", 
errno); 
return —-1; 


} 


/* Next write the ccsid values */ 


bw = write(fd, ccsidBuf, ccsidBufSize) ; 

if (bw == -1) 

{ 
printf ("write() of ccsid values failed. errno = %$d\n", errno); 
return —-1; 


} 
/* Now write the size (in bytes) of the listBuf */ 


bw = write(fd, &listBufSize, sizeof(int)); 

if (bw == -1) 

{ 
printf ("write() of listBufSize failed. errno = %d\n", errno); 
return —-1; 


} 
/* Finally write the listBuf containing the variable strings*/ 


bw = write(fd, listBuf, listBufSize); 

if (bw == -1) 

{ 
printf ("write() of listBuf failed. errno = %d\n", errno); 
return -1; 


} 


/* Close the file */ 

re = close(fd); 

if(re != 0) 

{ 
printf ("close() failed. errno = %d\n", errno); 
return —-1; 


} 


printf ("System-level environment variables saved\n") ; 
return 0; 


Restoring System-Level Environment Variables 


This program reads the system-level environment variable list from a file and then sets the system-level environment variables. 
Use the Create C Module (CRTCMOD) and the Create Program (CRTPGM) commands to create this program. 


Call this program with one parameter (the name of the file in which the system-level environment variables were stored). 
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ie *Y. 
/* FUNCTION: Restore the system-level environment variable list */ 
fa and the associated CCSIDs stored in a file */ 
eg */ 
/* LANGUAGE: ILE C for OS/400 *y/ 
1g */ 
/* APIs USED: Qp0zPutSysEnv() */ 
/* */ 


[ORK RK KK KKK KK A A A A A A A RIA A A A A A I I I / 
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#include <fcntl.h> 
#include <stdio.h> 
#include <unistd.h> 
#include <sys/stat.h> 
#include <stdlib.h> 
#include <errno.h> 
#include <qp0z1170.h> 


int main(int argc, char *argv[]) 

{ 
int fd, rc, br, i, numvar; 
int ccsidBufSize = 0, listBufSize = 0, *ccsidBuf; 
char *listBuf; 


if (argc != 2) 

{ 
printf ("Usage: call %s <filename>\n",argv[0]); 
printf ("Example: call %s '/tmp/sev'\n",argv[0]); 
return —-1; 


} 


/* Open the file specified */ 


fd = open(argv[1], O_RDONLY) ; 

if(fd == -1) 

{ 
printf ("open() failed. errno = %d\n", errno); 
return —-1; 


} 


/* Get the number of variables */ 


br = read(fd, &numvar, sizeof(int)); 
if(br == -1) 
{ 
printf ("read() failed. errno = %d\n", errno); 


return —-1; 


/* Could delete the existing system-level environment */ 
/* variables and have only the restored values. */ 
/* If so desired, could call Qp0OzD1tSysEnv() to do so */ 


/* If there aren't any elements in the file, skip the rest of */ 
/* the reads and go to the end */ 


if(numvar > 0) 

{ 
ccsidBufSize = numvar*sizeof (int); 
ccsidBuf = (int *)malloc(ccsidBufSize) ; 


/* Read the ccsid values and put it in ccsidBuf */ 
br = read(fd, ccsidBuf, ccsidBufSize); 
if (br == -1) 
{ 
printf ("read() failed. errno = %d\n", errno); 
return -1; 


} 


/* Read the size of the list buffer and put it in listBufSize */ 
br = read(fd, &listBufSize, sizeof(int)); 
if (br == -1) 
{ 
printf ("read() failed. errno = %d\n", errno); 
return -1; 


} 
listBuf = (char *)malloc(listBufSize); 


/* Finally read the strings themselves */ 

br = read(fd, listBuf, listBufSize); 

if (br == -1) 

{ 
printf ("read() failed. errno = %d\n", errno); 
return —-1; 

} 

} 


/* Walk through the buffer and get the */ 
/* name=value strings one by one */ 
/* Use QpOzPutSysEnv() to set the values */ 


for(i = 0; i < numvar; itt) 

{ 
re = Qp0zPutSysEnv(listBuf, ccsidBuf[i], NULL); 
if(rce != 0) 
{ 


printf ("Qp0zPutSysEnv() failed. rc=%d\n",rc); 
return -1; 


} 


listBuf += strlen(listBuf) + 1; 
} 


close (fd); 


printf ("System-level environment variables restored\n") ; 
return 0; 


Using ILE Common Execution Environment Data APIs 


The following examples show how to call the ILE Common Execution Environment (CEE) Date APIs for ILE COBOL and ILE 
RPG. 


PROCESS NOMONOPRC. 
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This sample ILE COBOL program demonstrates how to call the 
Common Execution Environment (CEE) Date APIs. The program 
accepts two parameters. The first is the date in character 


form and the second the format of the date. For instance 
CALL CEEDATES ('10131955' '"MMDDYYYY') causes the program 
to treat the date as October 13 1955). 


The program then displays on the console the numeric day of 
the week for that date (Sunday = 1) and the named day of 
week for that date. 


+ FF + + F FF F F F OF 
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IDENTIFICATION DIVISION. 

PROGRAM-ID. CEEDATES. 

ENVIRONMENT DIVISION. 

CONFIGURATION SECTION. 

SPECIAL-NAMES. 

LINKAGE TYPE PROCEDURE FOR "CEEDAYS" USING ALL DESCRIBED, 
LINKAGE TYPE PROCEDURE FOR "CEEDYWK" USING ALL DESCRIBED, 
LINKAGE TYPE PROCEDURE FOR "CEEDATE" USING ALL DESCRIBED. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

O01 Lilian-Date PIC S9( 
01 Day-of-—Week-Numeric PIC S9( 
01 Day-of-Week-Alpha PIC X(1 
O01 Day-of-—Week-Format PIC X(1 
LINKAGE SECTION. 


BINARY. 
BINARY. 


VALUE "Wwwwwwwwwz". 


01 Sample-Date PIC X(8). 

O01 Date-Format PIC X(8). 

PROCEDURE DIVISION USING Sample-Date, Date-Format. 
SAMPLE. 


Convert formatted date to Lilian date 


CALL "CEEDAYS" USING Sample-Date 
Date-Format 
Lilian-Date 
OMITTED. 


* Get numeric day of week from Lilian date 


CALL "CEEDYWK" USING Lilian-Date 
Day-of—Week-Numeric 
OMITTED. 


* 


* Get day of week from Lilian date 
* 
CALL "CEEDATE" USING Lilian-Date 
Day-of-—Week-Format 
Day-of-—Week-Alpha 


OMITTED. 
DISPLAY "Day of week = " Day-of—Week-Numeric UPON CONSOLE. 
DISPLAY "Day of week = " Day-of-Week-Alpha UPON CONSOLE. 


STOP RUN. 


D * eK eK KK KK KK KK KK KK 
D * 

D* This sample ILE RPG program demonstrates how to call the 

D* Common Execution Environment (CEE) Date APIs. The program 
D* accepts two parameters. The first is the date in character 
D* form and the second the format of the date. For instance 
D* CALL CEEDATES ('10131955' 'MMDDYYYY') causes the program 

D* to treat the date as October 13 1955). 

D * 

D* The program must be compiled with DFTACTGRP (*NO) 

D * 
D* The program then displays on the console the numeric day of 
D* the week for that date (Sunday = 1) and the named day of 

D* week for that date. 


D * 

D * Re ee I I KK KK KK KK 
DLilianDate s 101i 0 

DDayOfWkN s 10i O 

DDayOfwkA s 10 

DDayOfwkFmt s 10 inz ('Wwwwwwwwwz ' ) 
Cc *entry plist 

c parm SampleDate 8 
Cc parm DateFormat 8 
c* 

C* Convert formatted date to Lilian date 

c* 

Cc callb(d) "CEEDAYS' 

Cc parm SampleDate 
€ parm DateFormat 
Cc parm LilianDate 
Cc parm *OMIT 

c* 

C* Get numeric day of week from Lilian date 

c* 

Cc callb(d) "CEEDYWK' 

Cc parm LilianDate 
Cc parm DayOfWwkN 

c parm *OMIT 

c* 

C* Get day of week from Lilian date 

c* 

Cc callb(d) "CEEDATE' 

Cc parm LilianDate 
Cc parm DayOfWwkFmt 
Cc parm DayOfWkA 

e parm *OMIT 

c* 

Cc DayOfwkN dsply 

c DayOfWkA dsply 

Cc eval *kinlr = VL" 

c return 


Using the Generic Terminal APIs 


The following two examples illustrate programs that implement a generic terminal and a simple interpreter. 


Terminal Program 


This program starts and runs a generic terminal. 


This program demonstrates the use of the generic terminal functions QpOzStartTerminal(), Qp0zRunTerminal(), Qp0zEndTerminal(), 
and Qp0zGetTerminalPid(). 


Use the Create Bound C Program (CRTBNDC) command to create this program (see Creating the Terminal and Interpreter 


Programs). 


Call this program with no parameters (see Calling the Terminal Program). 


/* Includes */ 
#include <qp0ztrml.h> 
#include <qp0z1170.h> 
#include <stdlib.h> 
#include <stdio.h> 


/* Constants */ 
#define NUM_PREDEFINED_ENVS 2 


/* Global Variables */ 
extern char **environ; 


int main (int argc, char *argv[]) 


{ 


char *args[2]; /* Argument array */ 

int envCount; /* Count of currently defined env vars */ 
int index; /* Loop index */ 

char **envp; /* For walking environ array */ 

char **envs; /* Environment variable array */ 
Qp0z_Terminal_T handle; /* Terminal handle */ 
Qp0z_Terminal_Attr_T ta; /* Terminal attributes */ 

pid_t pid; /* Process ID of interpreter */ 

int re; /* Return code */ 


[ORK RK KK KK KK KK I A A IA A IA A A A A A A A oe a / 


/* Build the argument array. */ 
[ORK RK KK KK KK KK IK IA IA A A A A A A AA IA A A A / 


"/QSYS.LIB/QGPL.LIB/ECHOINT.PGM"; 
NULL; 


args [0 
args[l 


[KOR KK KK KK KK KK IK A A A A A A I A AAA AA I A A I A I / 


/* Build the environment variable array. */ 
[ORK RK KK KK KK KKK IK AA IA A IA A A AR AA IA A A A I / 


/* Make sure environ is set in this activation group. */ 
QpOzInitEnv(); 


/* Count the number of environment variables currently defined in this 
process. Qp0zStartTerminal() will make sure the interpreter 
process does not have too many environment variables. */ 

for (envCount = 0, envp = environ; *envp != NULL; ++envp, ++envCount); 


/* Allocate storage for the environment variable array. */ 
envs = (char **)malloc(sizeof(char *) * 

(envCount + NUM_PREDEFINED_ENVS) ); 
if (envs == NULL) { 


perror("malloc() failed"); 
exit (1); 
} 


/* Copy the current environment variables to the array. */ 
for (index = 0; environ[index] != NULL; ++index) { 
envs [index] = environ[index]; 


} 


/* Set QIBM_USE_DESCRIPTOR_STDIO variable for using descriptors. This 
will override the current value of the variable. */ 
envs [index++] = "QIBM_USE_DESCRIPTOR_STDIO=Y"; 


/* Null terminate array of environment variables. */ 
envs [index] = NULL; 


[ORK KK RK KK KK KK I AA A A A A A A A A A I / 


/* Set the terminal attributes. */ 


[ORK KK KK RK KK AK AA A A A A A A A AA A A A I / 


memset (&ta, '\0', sizeof (Qp0z_Terminal_Attr_T)); 
ta.Buffer_Size = 8196; 
ta.Inherit.pgroup = SPAWN_NEWPGROUP; 


ta.Title = "Echo Interpreter"; 
ta.Cmd_Key_Linel = "F3=Exit F9=Retrieve"; 
ta.Cmd_Key_Line2 = "F17=Top F18=Bottom"; 


[KOR KK KK KK KK KK IK A A A A A I A AA AA A A A I / 


/* Start and run the terminal. */ 
[ORK KK KK KKK KK I IA IA A A A A A A A I A A He A / 


/* Start the terminal. */ 


if (QpOzStartTerminal (handle, args, envs, ta) != 0) { 
perror("Qp0zStartTerminal() failed"); 
exit (1); 


} 


/* Get the PID of the interpreter process. */ 


if (QpO0zGetTerminalPid(handle, &pid) != 0) { 
perror ("Qp0zGetTerminalPid() failed"); 
exit (1); 


} 


/* Run the terminal. */ 
re = Qp0OzRunTerminal (handle) ; 
switch (rc) { 
case QPOZ_ TERMINAL _F12: 
case QP0OZ_ TERMINAL _F3: 
case QP0Z_TERMINAL_ENDED: 
/* Do nothing */ 
break; 


default: 
perror ("Qp0zRunTerminal() failed"); 
exit(1); 
break; 


} 


/* End the terminal. */ 
Qp0zEndTerminal (handle) ; 


return 0; 


Interpreter Program 


This program is a simple echo interpreter that is used by the terminal program (see Terminal Program). 


Use the Create Bound C Program (CRTBNDC) command to create this program (see Creating the Terminal and Interpreter 


Programs). 


/* Echo interpreter */ 
#include <stdio.h> 
#include <signal.h> 
#include <stdlib.h> 


static void SignalHandler (int); 


int main (int argc, char *argv[]) 


{ 


} 


char buffer[8192]; /* Buffer for reading input */ 
struct sigaction sigact; /* Signal action */ 


/* Set up a signal handler for SIGHUP. The terminal 
sends this signal when the user presses F3 to exit. */ 

sigemptyset (&sigact.sa_mask); 

sigact.sa_flags = 0; 

sigact.sa_handler = SignalHandler; 


if (sigaction(SIGHUP, &sigact, NULL) != 0) { 
perror("sigaction(SIGHUP) failed."); 
exit (2); 


} 


/* Set up a signal handler for SIGINT. The terminal sends 
this signal when the user presses SysReq 2. */ 

sigemptyset (&sigact.sa_mask); 

sigact.sa_flags = 0; 

sigact.sa_handler = SignalHandler; 


if (sigaction(SIGINT, &sigact, NULL) != 0) { 
perror("sigaction(SIGINT) failed."); 
exit (2); 


} 


/* Switch stdout to use line-mode buffering. */ 
setvbuf (stdout, NULL, _IOLBF, 128); 

printf ("Echo interpreter starting ...\n"); 
printf ("Enter text:\n"); 


/* Do forever. */ 

while (1) { 
/* Read a line from stdin. */ 
gets (buffer); 


/* End and clean up any allocated 
resources when stdin is closed. */ 

if (feof(stdin)) { 
printf("Echo interpreter ending ...\n"); 
exit(0); 

} 

/* Echo the line to stdout. */ 

printf("%s\n", buffer); 

} /* End of while */ 


return 0; 


void 
SignalHandler(int signo) 


{ 


printf ("Ending for signal %d\n", signo); 
exit (1); 


Creating the Terminal and Interpreter Programs 


The following examples show how to create the example programs (Terminal Program and Interpreter Program). These examples 


assume that the source for the terminal program is member TERMINAL in the file QGPL/QCSRC and that the source for the 
interpreter program is member INTERPRET in the file QGPL/QCSRC. 


Create the terminal program: 


CRTBNDC PGM(QGPL/TERMINAL) 
SRCFILE (QGPL/QCSRC) 
SRCMBR (TERMINAL) 
SYSIFCOPT (*IFSIO) 
TEXT ('Example Terminal program') 


Create the interpreter program: 


CRTBNDC PGM(QGPL/INTERPRET) 
SRCFILE (QGPL/QCSRC) 
SRCMBR (INTERPRET) 
SYSIFCOPT (*IFSIO) 
TEXT ('Example Interpreter program') 


Calling the Terminal Program 
The following example shows how to start the example program: 


CALL PGM(QGPL/ TERMINAL) 


Using Profile Handles 


The following example illustrates how to generate, change, and release profile handles in a CL program. 


[BORK RK KK KKK KK KK IR AA IA A I A A AA AAA A A A I A I 
[BKK RK KK KK KK KK A IA A A A A AA IA A IA A A A I I 


i> */ 
/* FUNCTION: Illustrates how to generate, change, and release */ 
/* profile handles in a CL program. */ 
/* */ 
/* LANGUAGE: CL */ 
La af, 
/* APIs USED: QSYGETPH — Get Profile Handle */ 
/* QWISETP - Set Profile */ 
/* QSYRLSPH - Release Profile Handle */ 
iF af 


[ORK RK KK KK KKK IK IA AA IA A I I AR AA IA AA IA A A I A I I / 
[BKK RK KK KK KK KK A IA A A A A A A AA IA IA IA A I A A I I ok / 


PGM (&USERID &PWD) 


/* Declare the variables needed by this program: ey 
DCL VAR(&USERID) TYPE(*CHAR) LEN(10) 

DCL VAR(&PWD) TYPE(*CHAR) LEN (10) 

DCL VAR(&SECOFR) TYPE(*CHAR) LEN(10) VALUE (QSECOFR) 

DCL VAR(&SECPWD) TYPE(*CHAR) LEN(10) VALUE (*NOPWD) 


DCL VAR(&PRFHNDL1) TYPE(*CHAR) LEN(12) 


DCL VAR (&PRFHNDL2) TYPE(*CHAR) LEN(12) 

/* Generate profile handles for the QSECOFR user ID and ia 
/* for the user ID passed to this program: */ 
CALL PGM(QSYGETPH) PARM(&SECOFR &SECPWD &PRFHNDL1) 

CALL PGM(QSYGETPH) PARM(&USERID &PWD &PRFHNDL2) 


/* Change the user for this job to the user ID passed to */ 
/* this program: */ 


CALL PGM(QWTSETP) PARM(&PRFHNDL2) 


/* This program is now running under the user ID passed to */ 
/* this program. sae A 


/* Now change the user ID for this job back to the QSECOFR */ 
/* user ID: * / 


CALL PGM(QWITSETP) PARM(&PRFHNDL1) 


/* The profile handles generated in this program can now */ 


/* be released: *y 
CALL PGM(QSYRLSPH) PARM(&PRFHNDL1) 

CALL PGM(QSYRLSPH) PARM(&PRFHNDL2) 

ENDPGM 


Using Registration Facility APIs 


The following is an example of how to use the registration facility in one of your programs. The example does not include any of the 
programs that are being called, nor does it show anything but an excerpt of the calling program. 


The first thing to do, after deciding in what program object the exit point is to be placed, is to register that exit point. It is also 


important to remember that the exit point format defines what the exit program data looks like. Here is an example ILE C program 
that registers an exit point named QIBM_QXIC_TSTXPOINTA. 


[KK RK KK KK KK KKK A IR IA AA I I A AAA A A IA A a I I / 


/* PROGRAM: RegisterPoint */ 
aa Ky. 
/* LANGUAGE: ILE C for OS/400 *f 
(hg */ 
/* DESCRIPTION: This program registers an exit point in an */ 
f% application. *f 
/* */ 
/* APIs USED: QusRegisterExitPoint */ 
eg */ 


[ORK RK KR KK KK I IR IA AA A I I AA A AA A A A I He 


#include <string.h> 
#include <qusec.h> 
#include <qusrgfal.h> 


[KKK KK KKK KK KKK IK IA IA A I I I A AA AA A AA A a A / 


/* Structure for the control block */ 
[KKK KK KK KK KKK IK IA IA IA I I IA AA AA AA A A I I He  / 


typedef _Packed struct Control_x{ 


int Num_Vlen_Recs; 
Qus_Vlen_Rec_4_t Vlen_Rec_1; 
char Description[50]; 


} Control_Rec; 


int main () { 


Qus_EC_t Error_Code = {0}; 

char EPnt_Name [20] = "QIBM QXIC_TSTXPOINTA"; 
char EPnt_F_Name[8] = "USUSOOOO"; 

int EProg_Number = -l; 


Control_Rec EPnt_Controls 


{0}; 


[KK RK KK KR KR IR A A OK 


*x* INITIALIZING ALL STRUCTURES: : oA 


TKK KR AA A IA A A I I I / 


Error_Code.Bytes_Provided = sizeof (Error_Code) ; 


EPnt_Controls.Num_Vlen_Recs = 1; 
EPnt_Controls.Vlen_Rec_1.Length_Vlen_Record = 62; 
EPnt_Controls.Vlen_Rec_1.Control_Key = 8; 
EPnt_Controls.Vlen_Rec_1.Length_Data = 50; 

memcpy ( EPnt_Controls.Description , "Example Exit Point" , 17 ); 


QusRegisterExitPoint (EPnt_Name, 
EPnt_F_Name, 
&EPnt_Controls, 
&Error_Code) ; 
if ( Error_Code.Bytes_Available ) { 
printf ("\nEXCEPTION : %s",Error_Code.Exception_Idqd) ; 
exit (1); 


return (0); 


} 


After an exit point has been registered, exit programs must be added to that point, indicating the possible calls based on run-time 
conditions. The following is an example in ILE C, of how to add an exit program to a registered exit point. The exit program named 
TSTXITPROGQGPL is added to the exit point registered in the previous example named QIBM_QXIC_TSTXPOINTA. 


[KK RK KK KKK KK KK IK IA IA IA I A A AAA A A A I I / 


/* PROGRAM: AddProgram mf 
/* */ 
/* LANGUAGE: ILE C for OS/400 */ 
is */ 
/* DESCRIPTION: This program adds an exit program to a registered */ 
/* exit point. vA 
‘fag */ 
/* BPIs USED: QusAddExitProgram */ 
/* *f 


[ORK RK KKK KKK KK KK KK IA IA A I A A A AA AA A A a Ie a / 


#include <qusec.h> 
#include <qusrgfal.h> 


[OK KK KK KK KK KKK IK IA IA IA I I A AAA IA A A I I / 


/* Structure for the Exit Program Attributes *f 
KKK KK KK KKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKKKKKKKKK KKK KKKKK 
/ / 


typedef _Packed struct Xit_Att{ 


int Num_Vlen_Recs; 
Qus_Vlen_Rec_4_t ADPG_Vlen; 

int CCSID; 

char Reserved; 


} Xit_Attributes; 
int main () { 


Qus_EC_t Error_Code = {0}; 


char EPnt_Name [20] = "QIBM _QXIC_TSTXPOINTA"; 


char EPnt_F_Name [8] = "USUSOOOO"; 

int EProg_Number = -l; 

char Q EFProg_Name[20] = "TSTXITPROGOQGPL WS 
char EProg_Data[10] = "EXAMPLE Ws 

int Len_EProg_Data = sizeof (EProg_Data) ; 


Xit_Attributes EProg_Attributes; 


Error_Code.Bytes_Provided=sizeof (Error_Code) ; 


EProg_Attributes.Num_Vlen_Recs=1; 
EProg_Attributes.ADPG_Vlen.Length_Vlen_Record=16; 
EProg_Attributes.ADPG_Vlen.Control_Key=3; 
EProg_Attributes.ADPG_Vlen.Length_Data=4; 
EProg_Attributes.CCSID = 37; 


QusAddExitProgram (EPnt_Name, 
EPnt_F_Name, 
EProg_Number, 
Q_EProg_Name, 
EProg_Data, 
Len_EProg_Data, 
&EProg_Attributes, 
&Error_Code) ; 
if ( Error_Code.Bytes_Available ) { 
printf ("\nEXCEPTION : %s",Error_Code.Exception_Idqd) ; 
exit (1); 
} 
return (0); 


} 


When you have registered an exit point and have added the exit programs to that exit point, you can do exit program calls from within 
your application. The information needed to do the calls is obtained from the Retrieve Exit Information API. In the following sample 
a conditional call is made based on the exit point information. 


[ORK RK KK KKK KK KKK KK AA IA A I I A AAA AA A A I A / 


/* PROGRAM: RetrieveAndProcess */ 
/* aw 
/* LANGUAGE: ILE C for OS/400 */ 
f* *f 
/* DESCRIPTION: This is an excerpt of a program that retrieves */ 
/* information on an exit point, and does processing */ 
pe based on that information. */ 
/* mf 
/* APIs USED: QusRetrieveExitInformation * / 
es */ 


[KKK KK KK KK KKK IA AA AA IA I I A A A A A A a I I / 
#include <stdio.h> 

#include <stdlib.h> 

#include <string.h> 

#include <qusec.h> 

#include <qusrgfa2.h> 


[OK KK KK KKK KK IK IA IA IA IA I I AA AAA AA A A a a I A / 


/* Structure for Selection Criteria on the Retrieve ay, 
[ORK RK KK KK KK KKK IK IA AA IA I I I A AA AAA A A a I I / 


typedef _Packed struct RIVEI_Select_C_x { 


Qus_Selcrtr_t Crit; 
Qus_Select_Entry_t Select_Entry; 
char RTV_String[10]; 


} RTVEI_Select_C; 


[ORK RK KK KK KK KK A AA KA IA A AAA AA AA A A a Ie A / 


/* Conv_Lib converts the library name to a null terminated string */ 
[ORK RK KK KKK KK KKK KK AA IA IA I A A AAA AA A A a I A / 


char * Conv_Lib(char in_lib[], char *tmp) { 


int x = 0; 

while ( (in_lib[x] != ' ') && 
*tmp=in_lib[x++]; 
tmpt++; 


} 


return (tmp) ; 


} 


int main() { 


Qus_EXTI0200_t *EXTIO200; 

Qus_EXTIO200_Entry_t *EXTI0200_Entry; 

char *Pgm_Data; 

Qus_EC_t Error_Code= {0}; 

char EPnt_Name [20] "QIBM QXIC_TSTXPOINTA"; 
char EPnt_F_Name[8] = "USUSOOOO"; 

int EProg_Number = -1; 

int Counter; 

char *x*tmp_str; 

char *lib; 

char Handle[16] =" Ws 
int Length_Of_R_Var; 

char RTIVEI_Format_Name [8]; 


RTIVEI_Select_C EProg_Select_C = 


x!=10 ) { 


{0}; 


[OK KK KK KK A A A OK OK OK 


* Initializing Structures 


* 


TKK KA A IA AA A A I I / 


Error_Code.Bytes_Provided = sizeof (Error_Code) ; 


tmp_str=(char *)malloc(sizeof(char)); 


lib=(char *)malloc(sizeof (char) ); 


EXTIO200=(Qus_EXTIO200_t *) malloc 
sizeof( Qus_EXTI0200_Entry_t 


) 


( sizeof ( Qus_EXTI0O200_t 


EProg_Select_C.Crit.Number_Sel_Criteria = 1; 
EProg_Select_C.Select_Entry.Size_Entry = 26; 
EProg_Select_C.Select_Entry.Comp_Operator = 1; 


v 
EProg_Select_C.Select_Entry.Start_Pgm_Data = 0; 
EProg_Select_C.Select_Entry.Length_Comp_Data = 


memcpy ( EProg_Select_C.RTV_String , 


Length_Of_R_Var = (sizeof( Qus_EXTIO200_t ) + 
sizeof( Qus_EXTI0200_Entry_t ) + 


MAX_PGM_DATA_ SIZE) *2; 
memcpy ( RTVEI_Format_Name , "EXTIO200" , 8 ); 


QusRetrieveExitInformation (Handle, 
EXTIO200, 
Length_Of_R_Var, 
RTVEI_Format_Name, 
EPnt_Name, 
EPnt_F_Name, 
EProg_Number, 
&EProg_Select_C, 
&Error_Code) ; 


if ( Error_Code.Bytes_Available ) 
printf ("\nEXCEPTION 
exit (1); 


{ 


"EXAMPLE ns 


$s",Error_Code.Exception_Id) ; 


+ MAX PGM_DATA_SIZE 


) 


ae, 


) 
i 


+ 


[KK RK KK KK KKK KA A A A I A A A A A A a I 


* Call all of the preprocessing exit programs returned * 
Fe KK A A AA A A A I A A A A A A A a I 


Counter=EXTI0200->Number_Programs_Returned; 


while ( Counter-- ) { 


EXTIO200_Entry (Qus_EXTI0O200_Entry_t *) EXTI0200; 

EXTIO200_Entry = (Qus_EXTI0200_Entry_t *) ((char *)EXTIO200 + 
EXTI0200->0ffset_Program_Entry) ; 

Pgm_Data = (char *) EXTIO200_Entry; 

Pgm_Data += EXTI0O200_Entry->Offset_Exit_Data; 


Conv_Lib (EXTI0200_Entry-—>Program_Library,1lib); 


sprintf( tmp_str , "CALL %s/%.10s %.*s" , 
lib, 
EXTIO200_Entry-—>Program_Name, 
EXTIO200_Entry-—>Length_Exit_Data, 
Pgm_Data ); 

system( tmp_str ); 


[BORK RK KK KKK KK KK IA A A A RA A A A 


* This is where Error Handling on the exit program * 
* would be done. * 
Fe KK KR AA IR AA A A A A A A A A I A A A He I 
if ( Counter ) { 
memcpy (EXTI0200->Continue_Handle, Handle,16); 
QusRetrieveExitInformation (Handle, 
EXTIO200, 
Length_Of_R_Var, 
RTIVEI_Format_Name, 
EPnt_Name, 
EPnt_F_Name, 
EProg_Number, 
&EProg_Select_C, 
&Error_Code) ; 
if ( Error_Code.Bytes_Available ) { 
printf ("\nEXCEPTION : %s",Error_Code.Exception_Id) ; 
exit (1); 


} 


return (0); 


Using Semaphores and Shared Memory 


The following two examples illustrate programs that support the client/server model. 


Server Program 


This program acts as a server to the client program (see Client Program). The buffer is a shared memory segment. The process 
synchronization is done using semaphores. 


Use the Create C Module (CRTCMOD) and the Create Program (CRTPGM) commands to create this program. 


Call this program with no parameters before calling the client program. 


[ORK RK KK KKK KK KK I IA A A A A A A IA IA A A A A a I I IK / 
[BORK RK KK KK KK KK A IK A A A A A A AAA IA A A A A I / 


/* FUNCTION: This program acts as a server to the client program. and 
fe wif. 
/* LANGUAGE: ILE C for OS/400 i 
iE* */ 
/* APIs USED: semctl(), semget(), semop(), */ 
/* shmat(), shmctl(), shmdt(), shmget () */ 
iss */ 


[ORK RK KK KK KK KK I IA A A A RR A AA A A A A A A I I / 
[ORK RK KK KK KK KK KK A A A A A A A A IA AA A A A A A I I / 


#include <stdio.h> 

#include <string.h> 
#include <sys/ipc.h> 
#include <sys/sem.h> 
#include <sys/shm.h> 


#define SEMKEY 8888 /* Key passed into semget operation */ 
#define SHMKEY 9999 /* Key passed into shmget operation */ 
#define NUMSEMS 2 /* Num of sems in created sem set */ 
#define SIZEOFSHMSEG 50 /* Size of the shared mem segment */ 
#define NUMMSG 2 /* Server only doing two "receives" 

on shm segment ey: 


int main(int argc, char *argv[]) 
{ 
int rc, semid, shmid, i; 
void *shm_address; 
struct sembuf operations [2]; 
struct shmid_ds shmid_struct; 
short sarray[NUMSEMS]; 


/* Create a semaphore set with the constant key. The number of */ 


/* semaphores in the set is two. If a semaphore set already aw 
/* exists for the key, return an error. The specified permissions*/ 
/* give everyone read/write access to the semaphore set. Kf 


semid = semget ( SEMKEY, NUMSEMS, 0666 | IPC_CREAT | IPC_EXCL ); 
if ( semid == -1 ) 
{ 
printf ("main: semget() failed\n"); 
return -1; 


} 


/* Initialize the first semaphore in the set to 0 and the */ 
/* second semaphore in the set to 0. */ 
fe */ 
/* The first semaphore in the sem set means: A 
/* '1' —- The shared memory segment is being used. Bid 
Wt 'Q' -- The shared memory segment is freed. ay A 
/* The second semaphore in the sem set means: ar 
/* '1' -- The shared memory segment has been changed by */ 
/* the client. * 
/* 'O' -- The shared memory segment has not been */ 
/* changed by the client. */ 
sarray[0] = 0; 

sarray[1] = 0; 


/* The '1' on this command is a no-op, because the SETALL command*/ 
/* is used. */ 
re = semctl( semid, 1, SETALL, sarray); 
if(re == -1) 

{ 


printf ("main: semctl() initialization failed\n"); 
return -1; 


} 


/* Create a shared memory segment with the constant key. The 


/* size of the segment is a constant. The specified permissions 


/* give everyone read/write access to the shared memory segment. 
/* If a shared memory segment already exists for this key, 
/* veturn an error. 


shmid = shmget (SHMKEY, SIZEOFSHMSEG, 0666 | IPC_CREAT IPC_EXCL) 


if (shmid == -1) 
{ 
printf ("main: shmget() failed\n"); 
return -1; 


} 


/* Attach the shared memory segment to the server process. 
shm_address = shmat(shmid, NULL, 0); 
if ( shm_address==NULL ) 
{ 
printf("main: shmat() failed\n"); 
return -1; 
} 
printf ("Ready for client jobs\n"); 


/* Loop only a specified number of times for this example. 
for (i=0; i < NUMMSG; i++) 
{ 
/* Set the structure passed into the semop() to first wait 
/* for the second semval to equal 1, then decrement it to 
/* allow the next signal that the client writes to it. 
/* Next, set the first semaphore to equal 1, which means 
/* that the shared memory segment is busy. 
operations[0].sem_num = 1; 
/* Operate on the second sem 
operations[0].sem_op = -1; 
/* Decrement the semval by one 
operations[0].sem_flg = 0; 
/* Allow a wait to occur 


operations[1].sem_num = 0; 
/* Operate on the first sem 
operations[1l].sem_op = 1; 
/* Increment the semval by 1 
operations[1].sem_flg = IPC_NOWAIT; 

/* Do not allow to wait 


rc = semop( semid, operations, 2 ); 
if (re == -1) 
{ 
printf("main: semop() failed\n"); 


return —-1; 


} 


/* Print the shared memory contents. 
printf ("Server Received : \"Ss\"\n", (char *) shm_address) ; 


/* Signal the first semaphore to free the shared memory. 
operations[0].sem_num = 0; 

operations[0].sem_op = -1; 

operations[0].sem_flg = IPC_NOWAIT; 


rc = semop( semid, operations, 1 ); 
if (re == -1) 
{ 
printf("main: semop() failed\n"); 


return —-1; 


ef 


*/ 
if: 


ead 


ae 


} /* End of FOR LOOP */ 


/* Clean up the environment by removing the semid structure, */ 
/* detaching the shared memory segment, and then performing */ 
/* the delete on the shared memory segment ID. */ 


re = semctl( semid, 1, IPC_RMID ); 
if (rce==-1) 
{ 
printf ("main: semctl() remove id failed\n"); 
return -1; 


re = shmdt (shm_address); 
if (rc==-1) 
{ 
printf ("main: shmdt() failed\n"); 
return —1; 


re = shmctl(shmid, IPC_RMID, &é&shmid_struct); 
if (rce==-1) 
{ 
printf ("main: shmctl() failed\n"); 
return -1; 


} 


return 0; 


} 


Client Program 


This program acts as a client to the server program (see Server Program). The program is run after the message Ready for client jobs 
appears from the server program. 


Use the CRTCMOD and CRTPGM commands to create this program. 


Call this program with no parameters after calling the server program. 


Ye ee ee a i ee ei ee i ee ee a a ee ie Af 
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/* */ 
/* FUNCTION: This program acts as a client to the server program. */ 
i */ 
/* LANGUAGE: ILE C for OS/400 x 
Le */ 
/* APIs USED: semget(), semop(), */ 
/* shmget (), shmat(), shmdt () af 
ea */ 


Yee ee a ee ee ee a i ee a ee ee aie Af 
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#include <stdio.h> 

#include <string.h> 
#include <sys/ipc.h> 
#include <sys/sem.h> 
#include <sys/shm.h> 


#define SEMKEY 8888 
#define SHMKEY 9999 


#define NUMSEMS 2 
#define SIZEOFSHMSEG 50 


int main(int argc, char *argv[]) 


{ 


struct sembuf operations [2]; 
void *shm_address; 
int semid, shmid, rc; 


/* Get the already created semaphore ID associated with key. */ 
/* If the semaphore set does not exist, then it will not be */ 
/* created, and an error will occur. *f 
semid = semget ( SEMKEY, NUMSEMS, 0666); 
if ( semid == -1 ) 
{ 
printf ("main: semget() failed\n"); 


return -1; 


} 


/* Get the already created shared memory ID associated with key. */ 
/* If the shared memory ID does not exist, then it will not be * / 
/* created, and an error will occur. */ 


shmid = shmget (SHMKEY, SIZEOFSHMSEG, 0666); 
if (shmid == -1) 
{ 
printf ("main: shmget() failed\n"); 
return -1; 


} 


/* Attach the shared memory segment to the client process. */ 
shm_address = shmat(shmid, NULL, 0); 
if ( shm_address==NULL ) 
{ 
printf("main: shmat() failed\n"); 
return -1; 


} 


/* First, check to see if the first semaphore is a zero. If it */ 
/* is not, it is busy right now. The semop() command will wait */ 
/* for the semaphore to reach zero before running the semop(). */ 
/* When it is zero, increment the first semaphore to show that */ 
/* the shared memory segment is busy. mf 
operations[0].sem_num = 0; 

/* Operate on the first sem * / 
operations[0].sem_op = 0; 

/* Wait for the value to be=0 ay 
operations[0].sem_flg = 0; 

/* Allow a wait to occur ay: 
operations[1].sem_num = 0; 

/* Operate on the first sem * / 
operations[1].sem_op = 1; 

/* Increment the semval by one */ 
operations[1].sem_flg = 0; 

/* Allow a wait to occur */ 
rc = semop( semid, operations, 2 ); 


if (re == -1) 
{ 
printf("main: semop() failed\n"); 
return -1; 


} 
strcpy((char *) shm_address, "Hello from Client"); 


/* Release the shared memory segment by decrementing the in-use */ 


/* semaphore (the first one). Increment the second semaphore to */ 
/* show that the client is finished with it. */ 
operations[0].sem_num = 0; 

/* Operate on the first sem */ 


operations[0].sem_op = -1; 


/* Decrement the semval by one Hf: 


operations[0].sem_flg = 0; 

/* Allow a wait to occur *f 
operations[1].sem_num = 1; 

/* Operate on the second sem */ 
operations[1].sem_op = 1; 

/* Increment the semval by one ay 
operations[1].sem_flg = 0; 

/* Allow a wait to occur es 
rc = semop( semid, operations, 2 ); 


if (re == -1) 


printf("main: semop() failed\n"); 
return -1; 


} 


/* Detach the shared memory segment from the current process. af 
rc = shmdt (shm_address); 
if (rce==-1) 


{ 
printf ("main: shmdt() failed\n"); 
return -1; 


} 


return 0; 


} 


Using SNA/Management Services Transport APIs 


This example shows a source and target application using network management transport APIs to send and receive management 
services data. The example compiles in ILE C. 


Source Application Program 
This source application program sends a request to a target application. 


[RK RK KKK KK KK KK IA A A A A A A IA IA A A A A A I I / 
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‘fag */ 
/* FUNCTION: xf 
/* This is a source application that uses the management services *f 
/* transport APIs. It does the following: */ 
/* 1. Prompts for the network ID and CP name of the remote system */ 
/* where target application MSTTARG has been started. aa 
/* 2 Prompts for data to be sent to MSTTARG. *if 
/* 3. Prompts for whether or not a reply is required. */ 
‘tags 4 Sends a management services transport request to MSTTARG. */ 
/* 5 Repeats steps 2-4 until QUIT is entered. */ 
ha */ 
/* Note: MSTTARG may be ended by this application by sending it the */ 
T* string "ENDRMTAPP". */ 
aa aes 
/* LANGUAGE: ILE C for OS/400 ee 
1% */ 
/* APIs USED: QNMSTRAP, QNMENDAP, QNMRCVDT, Af 
£* QONMSNDRQ, QNMCHGMN, QNMENDAP */ 
/* ef 


[ORK RK KKK KKK KK I AA A A A RK A AA IA A A A A A I I / 
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/* Includes xf 


[BORK RK KKK KK KK A IA A A A A RR IA AA AA A A A I I / 
#include <stdio.h> 
#include <string.h> 
#include <stdlib.h> 


#define NOERROR "NOERROR" 
#define ROSONLY "*RQS Md 
#define ROSRPY "*ROQSRPY " 
"bas */ 
/* Type definitions fare 
hes #e/. 
typedef int HANDLE; /* typedef for handle af 
typedef char APPLNAME[8]; /* typedef for application name */ 
typedef char NETID[8]; /* typedef for network ID */ 
typedef char CPNAME[8]; /* typedef for control point name*/ 
typedef char MODENAME[8]; /* typedef for mode name * / 
typedef char SENSECODE[8]; /* typedef for SNA sense code (in 
character format) os 
typedef char LIBNAME[10]; /* typedef for library name ef 
typedef char QNAME[10]; /* typedef for data queue name * / 
typedef char MSGID[7]; /* typedef for message ID * / 
typedef char EXCPDATA[48]; /* typedef for exception data */ 
typedef char CATEGORY[8]; /* typedef for category */ 
typedef char APPLTYPE[10]; /* typedef for application type */ 
typedef char REPLREG[10]; /* typedef for replace 
registration bas 
typedef char DATARCVD[10]; /* typedef for data received *ef 
typedef char REQTYPE[10]; /* typedef for request type */ 
typedef char POSTRPL[10]; /* typedef for post reply */ 
typedef char REQUESTID[53]; /* typedef for request ID */ 
typedef char SRBUFFER[500]; /* typedef for send/receive 
buffer. This program limits 
the amount of data to be sent 
or received to 500 bytes. The 
maximum size of a management 
services transport buffer is 
31739. iy. 
typedef struct { /* Library-qualified data queue 
name */ 
QNAME data_queue_name; /* data queue name */ 
LIBNAME library_name; /* library name Hf 
} QUALQNAME; 
typedef struct { /* Error code structure */ 
int bytes_provided; /* number of bytes provided *ef 
int bytes_available; /* number of bytes available */ 
MSGID exception_ID; /* exception ID */ 
char reserved_area; /* reserved */ 
EXCPDATA exception_data; /* exception data *f 
} ERRORCODE; 
typedef struct { /* Notification record structure */ 
char record_type[10]; /* Record type *if 
char function[2]; /* Function */ 
HANDLE handle; /* Handle */; 
REQUESTID req_id; /* Request ID */ 
char reserved[11]; /* Reserved area */ 
} NOTIFRCD; 
typedef struct { /* Receiver variable structure */ 
int bytes_provided; /* number of bytes provided *f 
int bytes_available; /* number of bytes available */ 
SRBUFFER received_data; /* received data */ 
} RECEIVERVAR; 
typedef struct { /* Qualified application name * / 


NETID network_id; /* Network ID */ 
CPNAME cp_name; /* Control point name */ 
APPLNAME app_name; /* Application name mf 
} QUALAPPL; 


ea */ 
/* External program declarations */f 
es a 
#pragma linkage (QNMSTRAP, OS) /* Start application API * / 
extern void QNMSTRAP (HANDLE *handle, /* pointer to handle bard 
APPLNAME *applname, /* pointer to appl name Kip 
QUALOQNAME *qualqname, /* pointer to data queue 
name */ 
ERRORCODE *errorcode); /* pointer to error code 
parameter */ 
#pragma linkage (QNMENDAP, OS) /* End application API */ 
extern void QNMENDAP (HANDLE *handle, /* pointer to handle */ 
ERRORCODE *errorcode); /* pointer to error code 
parameter */f 
#pragma linkage (QNMRCVDT, OS) /* Receive data API */ 
extern void QNMRCVDT (HANDLE *handle, /* pointer to handle */ 
RECEIVERVAR *rcvvar, /* pointer to receiver 
variable */ 
int *rcvvarln, /* pointer to receiver variable 
length *f 
REQUESTID *regqid, /* pointer to request ID */ 
QUALAPPL *qualappl, /* pointer to remote 
application name */ 
DATARCVD *datarcvd, /* pointer to type of data 
received *f 
int *waittim, /* pointer to wait time *y 
ERRORCODE *errorcode); /* pointer to error code 
parameter *f 
#pragma linkage (QNMSNDRQ, OS) /* Send request API *f 
extern void QNMSNDRQ (HANDLE *handle, /* pointer to handle */ 
QUALAPPL *qualappl, /* pointer to remote 
application name */ 
REQUESTID *reqid, /* pointer to request ID */ 
SRBUFFER *sndbuf, /* pointer to send buffer */ 


int *sndbufln, /* pointer to send buffer length*/ 
REQTYPE *reqtype, /* pointer to request type ays 


POSTRPL *postrpl, /* pointer to post reply a 
int *waittim, /* pointer to wait time *f 
ERRORCODE *errorcode); /* pointer to error code 
parameter */ 
#pragma linkage (QNMCHGMN, OS) /* Change mode name API es 
extern void QNMCHGMN (HANDLE *handle, /* pointer to handle */ 
MODENAME *modename, /* pointer to mode name ays 
ERRORCODE *errorcode); /* pointer to error code 
parameter *f 


void check_error_code (char func_name[8]); /* Used to check error code 


*/ 
void get_network_id (void); /* Get network ID of destination 
node */ 
void get_cp_name (void); /* Get CP name of destination 
node band 
void process_replies (void) ; /* Process replies received from 
destination application iy A 
/* */ 
/* Global declarations xf 


/* ad 


HANDLE appl_handle; /* Handle of application */ 
ERRORCODE error_code_struc = /* Error code parameter and 
{sizeof (error_code_struc), /* Initialize bytes provided */ 
0, /* initialize bytes available *eff 
NOERROR}; /* initialize error code */ 
char input_line[80]; /* Input data */ 
QUALAPPL qual_appl = /* Qualified application name Hf 
{ " ie " We " " } : 
REQUESTID req_id; /* Returned request ID ay: 
int wait_time = -1; /* Wait time = wait forever */ 
/* * 
/* Start of main. */ 
/* */ 
int main () 
{ 
APPLNAME appl_name = "MSTSOURC"; /* Application name to be used wf 
QUALONAME data_queue_parm = /* Data queue name to be used bap 

{"*NONE mom "}; /* Initialize structure */ 

NOTIFRCD notif_record; /* Area to contain notification 

record bid 
CATEGORY category = "*NONE ny /* SNA/Management Services function 

set group */ 
APPLTYPE appl_type = "*FPAPP "; /* Application type */ 
REPLREG replace_reg = "*YES "; /* Replace registration = *YES ¥*/ 
int sys_result; /* Result of system function */ 
char end_msg[] = "ENDRMTAPPL",; /* If this data is received then 

the application will end *f 
char incoming_data[] = "01"; /* Incoming data constant */ 
SRBUFFER send_buffer; /* Send buffer */ 
int data_length; /* Length of send data */ 
char input_char; /* Input character */ 
REQTYPE req_type; /* Request type ia 
POSTRPL post_reply = "*NO "; /* Don't post any received replies 

aes 

MODENAME mode_name = "#INTER "; /* Mode name = #INTER */ 
hea KL. 
/* Start of code Ke 
ie sai A 
QNMSTRAP (&appl_handle, 

é&appl_name, 

&data_queue_parm, 

é&error_code_struc) ; /* Start application ay: 
check_error_code ("QNMSTRAP") ; /* Check error code */ 
QNMCHGMN (é&appl_handle, 

&mode_name, 

&error_code_struc); /* Change mode name */ 
check_error_code ("QNMCHGMN") ; /* Check error code */ 
get_network_id(); /* Get network ID */ 
get_cp_name(); /* Get CP name * / 
memcpy (qual_appl.app_name, 

"MSTTARG ", 
sizeof (qual_appl.app_name)); /* Copy application name mf 
printf ("Enter message to send to remote application or " 
"QUIT to end\n"); 
gets (input_line); 
while (memcmp (input_line, 
"OULE", 
sizeof("QUIT")) != 0) /* While an ending string 
has not been entered iy 
{ 
data_length = strlen(input_line); /* Get length of message * / 
memcpy (send_buffer, 
input_line, 
data_length); /* Put message in send buffer */ 


printf ("Reply necessary? 


(Y or N)\n"); 


/* Prompt for reply 


indicator 
gets (input_line) ; /* Get reply character 
input_char = toupper(input_line[0]); /* Convert character to 
uppercase 
while (strlen(input_line) != 1 | | 
(input_char != 'Y' && 
input_char != 'N')) 


{ 
printf ("Please type Y or N\n"); 


gets (input_line) ; /* Get reply character 
input_char = toupper(input_line[0]); /* Convert character to 
uppercase 
} 
if (input_char == 'Y"') 
{ 
memcpy (req_type, 
RQSRPY, 
sizeof(req_type)); /* Indicate request should have 
a reply 


else 


{ 
memcpy (req_type, 
RQSONLY, 


ee 
“if 


ifs 


sizeof (req_type)); /* Indicate request should not have 


a reply 
} 
QNMSNDRQ (&appl_handle, 
&qual_appl, 
éreq_id, 
&send_buffer, 
&data_length, 
&req_type, 
&post_reply, 
éwait_time, 
&error_code_struc); /* Send request to remote 


application 
check_error_code ("QNMSNDRQ"); /* Check error code 
if (input_char == 'Y') 
{ 
process_replies(); /* Process one or more received 
replies 


} 


printf ("Enter message to send to remote application or " 
"QUIT to end\n"); 
gets (input_line) ; 
} 
QNMENDAP (&appl_handle, 


&error_code_struc) ; /* End the application 
return 0; 
} 
/* 
/* process_replies function 
/* 
void process_replies () 
{ 
RECEIVERVAR receiver_var = /* Receiver variable 
{sizeof (receiver_var)}; /* Initialize bytes provided 
int rcev_var_len = sizeof (receiver_var); /* Length of receiver 
variable 
DATARCVD data_rcvd = "*NODATA "; /* Type of data received 
QUALAPPL qual_appl; /* Sender of reply 


printf ("Received reply(s):\n"); 
while (memcmp (data_revd, 


Mf: 


wf 
Sif 


fs 


a 


"kRPYCPL ", 


sizeof (data_rcevd)) != 0) /* While final reply has not 


been received 


strncpy (receiver_var.received_data, 
"\O", 
sizeof (receiver_var.received_data)); /* Null out 
data buffer 
QNMRCVDT (&appl_handle, 
&éreceiver_var, 
&rcv_var_len, 
éreq_id, 
&qual_appl, 
&data_rcevd, 
éwait_time, 
é&error_code_struc); /* Receive reply 
check_error_code("QNMRCVDT"); /* Check error code 
printf ("%$1.500s\n",receiver_var.received_data); /* Print out 
reply 


} 


/* 


/* get_network_id function. 


/* 
void get_network_id () 
{ 
int count; 
printf("Enter network ID of remote system where MSTTARG " 
"application has been started\n"); /* Prompt for network 
ID 
gets (input_line); /* Get network ID 
while (strlen(input_line) <= 0 | | 
strlen(input_line) > 8) 
{ 
printf ("Network ID is too long or too short - try again\n"); 
gets (input_line); /* Get network ID 
} 
memcpy (qual_appl.network_id, 
input_line, 
strlen(input_line) ); /* Copy network ID 
for (count=0; count < strlen(input_line); count+t+) 
qual_appl.network_id[count] = 
toupper (qual_appl.network_id[count]); /* Convert 
input to uppercase 


} 


/* While network ID is not valid 


/* 


/* get_cp_name function. 


/* 
void get_cp_name () 
{ 
int count; 
printf("Enter CP name of remote system where MSTTARG application " 
"has been started\n"); /* Prompt for CP name 
gets (input_line); /* Get CP name 
while (strlen(input_line) <= 0 | | 
strlen(input_line) > 8) /* While CP name is not valid 
{ 
printf("CP name is too long or too short - try again\n"); 
gets (input_line); /* Get CP name 
} 
memcpy (qual_appl.cp_name, 
input_line, 
strlen(input_line) ); /* Copy CP name 
for (count=0; count < strlen(input_line); count+t) 
qual_appl.cp_name[count] = 


fs 


iA 


eh 
xf 


xf 


wed 


xf 


ays 


Pay 
of: 


ead 
ef 


ee 


a 


toupper (qual_appl.cp_name[count]); /* Convert 


input to uppercase */ 
} 
ae */ 
/* check_error_code - */ 
ag if 


void check_error_code (char func_name[8]) 
{ 
char *sense_ptr = error_code_struc.exception_data + 36; /* 
Pointer to sense code in 


exception data */ 
SENSECODE sense_code; /* SNA sense code */ 
if (error_code_struc.bytes_available != 0) /* Error occurred? */ 


{ 
printf("\n\nError occurred calling %1.8s.\n", func_name) ; 
memcpy (sense_code, 
sense_ptr, 
sizeof (sense_code) ); /* Copy sense code from exception 
data Kf 
printf("Error code is %1.7s, SNA sense code is %1.8s.\n", 
error_code_struc.exception_ID, 
sense_code); 
if (memcmp (func_name, 


"QNMSTRAP", 
sizeof (func_name)) != 0) /* Error did not occur on 
start application? */ 
{ 
QNMENDAP (&appl_handle, 
é&error_code_struc); /* End the application */ 
} 
exit (EXIT_FAILURE) ; /* Exit this program */ 


Target Application Program 
This target application receives requests from and returns replies to source applications. 
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/* a 
/* FUNCTION: wif. 
/* This is a target application that uses the management services *f, 
/* transport APIs. It receives management services transport */ 
/* requests from source application MSTSOURC and displays the data */ 
/* contained in the request. If the request specifies that a * 
/* reply needs to be sent, this program accepts input from the */ 
/* keyboard and sends one or more replies to the source application. */ 
los bays 
/* LANGUAGE: ILE C for OS/400 ai. 
/* ef, 
/* APIs USED: QNMSTRAP, QNMENDAP, QNMREGAP, QNMDRGAP, */ 
/* QNMRCVDT, QNMSNDRP, QNMRCVOC, QRCVDTAQ, */ 
/* QNMENDAP Af, 
Le */ 
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/* Includes Ff 
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#include <stdio.h> 
#include <string.h> 
#include <stdlib.h> 


#define NOERROR "NOERROR" 

#define REQUEST "*RQS Mi 
#define REQREPLY "*ROSRPY . 
#define REPLYINC "*RPYINCPL " 
#define REPLYCMP "*RPYCPL " 


/* Type definitions 


typedef int HANDLE; 

typedef char APPLNAME[8]; 
typedef char NETID[8]; 
typedef char CPNAME[8]; 
typedef char SENSECODE[8]; 


typedef char LIBNAME[10]; 
typedef char QNAME[10]; 
typedef char MSGID[7]; 
typedef char EXCPDATA[48]; 
typedef char CATEGORY[8]; 
typedef char APPLTYPE[10]; 
typedef char REPLREG[10]; 


typedef char DATARCVD[10]; 
typedef char REPLYTYPE[10]; 
typedef char REQUESTID[53] 
typedef char PACKED5 [3]; 
typedef char SRBUFFER[500]; 


LA 


typedef struct { 


QNAME data_queue_name; 
LIBNAME library_name; 
} QUALQNAME; 


typedef struct { 
int bytes_provided; 
int bytes_available; 
MSGID exception_ID; 
char reserved_area; 
EXCPDATA exception_data; 
} ERRORCODE; 


typedef struct { 
char record_type[10]; 
char function[2]; 
HANDLE handle; 
REQUESTID req_id; 
char reserved[11]; 
} NOTIFRCD; 


typedef struct { 
int bytes_provided; 
int bytes_available; 
SRBUFFER received_data; 
} RECEIVERVAR; 


typedef struct { 
NETID network_id; 
CPNAME cp_name; 
APPLNAME app_name; 


typedef for handle 

typedef for application name 
typedef for network ID 

typedef for control point name 
typedef for SNA sense code 

(in character format) 

typedef for library name 
typedef for data queue name 
typedef for message ID 

typedef for exception data 
typedef for category 

typedef for application type 
typedef for replace 
registration 

typedef for data received 
typedef for reply type 
typedef for request ID 
typedef for PACKED(5,0) 
typedef for send/receive 
buffer. This program limits 
the amount of data to be sent 
or received to 500 bytes. The 
maximum size of a management 
services transport buffer is 
3173 9% 


field 


Library-qualified data queue 
name 

data queue name 

library name 


Error code structure 
number of bytes provided 
number of bytes available 
exception ID 

reserved 

exception data 


Notification record structure 
Record type 

Function 

Handle 

Request ID 

Reserved area 


Receiver variable structure 
number of bytes provided 
number of bytes available 
received data 


Qualified application name 
Network ID 

Control point name 
Application name 


} QUALAPPL; 


hes: XL 
/* External program declarations * 
[Er xy 
#pragma linkage (QNMSTRAP, OS) /* Start application API */ 
extern void QNMSTRAP (HANDLE *handle, /* pointer to handle af 
APPLNAME *applname, /* pointer to application 
name */ 
QUALONAME *qualqname,/* pointer to data queue 
name ¥f 
ERRORCODE *errorcode); /* pointer to error code 
parameter */ 
#pragma linkage (QNMENDAP, OS) /* End application API * 
extern void QNMENDAP (HANDLE *handle, /* pointer to handle * / 
ERRORCODE *errorcode); /* pointer to error code 
parameter ay: 
#pragma linkage (QNMREGAP, OS) /* Register application API Ref, 
extern void QNMREGAP (HANDLE *handle, /* pointer to handle */ 
CATEGORY *category, /* pointer to category */ 
APPLTYPE *appltype, /* pointer to application 
type */ 
REPLREG *replreg, /* pointer to replace 
registration parameter */ 
ERRORCODE *errorcode); /* pointer to error code 
parameter */ 
#pragma linkage (QNMDRGAP, OS) /* Deregister application API */ 
extern void QNMDRGAP (HANDLE *handle, /* pointer to handle af 
ERRORCODE *errorcode); /* pointer to error code 
set group mf: 
#pragma linkage (QNMRCVDT, OS) /* Receive data API Kf 
extern void QNMRCVDT (HANDLE *handle, /* pointer to handle wf 
RECEIVERVAR *rcvvar, /* pointer to receiver 
variable * 
int *rcvvarln, /* pointer to receiver variable 
length xy 
REQUESTID *reqid, /* pointer to request ID */ 
QUALAPPL *qualappl, /* pointer to remote 
application name */ 
DATARCVD *datarcvd, /* pointer to type of data 
received ef 
int *waittim, /* pointer to wait time mf 
ERRORCODE *errorcode); /* pointer to error code 
parameter */ 
#pragma linkage (QNMSNDRP, OS) /* Send reply API *f 
extern void QNMSNDRP (HANDLE *handle, /* pointer to handle */ 
REQUESTID *regqid, /* pointer to request ID ia 
SRBUFFER *sndbuf, /* pointer to send buffer */ 


int *sndbufln, /* pointer to send buffer length*/ 
REPLYTYPE *rpltype, /* pointer to reply type 7A 


int *waittim, /* pointer to wait time */ 

ERRORCODE *errorcode); /* pointer to error code 
parameter aes 
#pragma linkage (QNMRCVOC, OS) /* Receive operation completion API 
bay 
extern void QNMRCVOC (HANDLE *handle, /* pointer to handle */ 
REQUESTID *reqid, /* pointer to request ID */ 

QUALAPPL *qualappl, /* pointer to remote 

application name */ 


ERRORCODE *errorcode); /* pointer to error code 
parameter i] 


#pragma linkage (QRCVDTAQ, OS) /* Receive data queue */ 
extern void QRCVDTAQ (QNAME *queue_name, /* pointer to queue name mf 
LIBNAME *lib_name, /* pointer to library name */ 
PACKED5 *rcd_len, /* pointer to record length */ 
NOTIFRCD *notifrced, /* pointer to notification 
record */ 
PACKED5 *waittime); /* pointer to wait time */ 
void check_error_code (char func_name[8]); /* Used to check error 
code *f 
er */ 
/* Global declarations */ 
is Hf, 
HANDLE appl_handle; /* Handle of application yA 
ERRORCODE error_code_struc = /* Error code parameter * 
{sizeof (error_code_struc), /* Initialize bytes provided */ 
0, /* initialize bytes available mf 
NOERROR}; /* initialize error code ef, 
fag */ 
/* Start of main function */ 
ea ia 
int main () 
{ 
ig  f: 
/* Local declarations *f. 
/* eh 
APPLNAME appl_name = "MSTTARG "; /* Application name to be used 7 
QUALQNAME data_queue_parm = /* Data queue name to be used */ 
{"MSTDTAQ ", “OQTEMP "}; /* Initialize structure */ 
NOTIFRCD notif_record; /* Area to contain notification 
record Law 
RECEIVERVAR receiver_var = /* Receiver variable */ 
{sizeof (receiver_var)}; /* Initialize bytes provided * / 
QUALAPPL qual_appl; /* Qualified application name */ 
DATARCVD data_rcvd; /* Type of data received */ 
CATEGORY category = "*NONE it /* SNA/Management Services function 
set group */ 
APPLTYPE appl_type = "*FPAPP ", /* Application type */ 
REPLREG replace_reg = "*YES "; /* Replace registration = *NO */ 
REPLYTYPE reply_cmp = REPLYCMP; /* Complete reply */ 
REPLYTYPE reply_inc = REPLYINC; /* Incomplete reply *f 
int sys_result; /* Result of system function ey: 
int rcv_var_len = sizeof (receiver_var); /* Length of receiver 
variable ¥ 
PACKED5 wait_time_p = "\x00\x00\x1D"; /* Packed value for wait time 
= -1, that is, wait forever */ 
PACKED5 record_len; /* Length of received data queue 
record */ 
int wait_forever = -1; /* Integer value for wait time = 
-1, that is, wait forever */ 
int no_wait = 0; /* Do not wait for I/O to 
complete *f 
char end_msg[] = “ENDRMTAPPL"; /* If this data is received then 
the application will end */ 
char incoming_data[] = "01"; /* Incoming data constant */ 
char inbuf[85]; /* Input buffer af 
SRBUFFER send_buffer; /* Send buffer for sending 
replies */ 
int reply_len; /* Length of reply data baie 
/* Lf 
/* Start of executable code */ 
/* */ 
sys_result = system("DLIDTAQ DTAQ(QTEMP/MSTDTAQ)"); /* Delete 
previous data queue (if any) */ 


sys_result system("CRTDTAQ DTAQ(QTEM 


QNMSTRAP (&appl_handle, 
é&appl_name, 
&data_queue_parm, 
&error_code_struc); 
check_error_code ("QNMSTRAP") ; 
QNMREGAP (&appl_handle, 
&category, 
&appl_type, 
&replace_reg, 
&error_code_struc); 


/* 
/* 


/* 


check_error_code ("QNMREGAP") ; es 
while (memcmp (receiver_var.received_da 
end_msg, 
sizeof(end_msg)) != 0) 
{ /* 


QRCVDTAQ (&data_queue_parm.data_qu 


&édata_queue_parm.library_ 


&record_len, 
énotif_record, 
éwait_time_p); /* 
if (memcmp (notif_record.function, 
incoming_data, 
sizeof (incoming_data) ) 


strncpy (receiver_var.received_ 

WN OWS 

sizeof (receiver_var.re 
QNMRCVDT (&appl_handle, 
&receiver_var, 
&rcv_var_len, 
énotif_record.req_id 
&qual_appl, 
&data_revd, 
éwait_forever, 
&error_code_struc) ; 


check_error_code ("QNMRCVDT") ; 
printf ("%1.500s\n", receiver_va 
if (memcmp (data_revd, 
REQREPLY, 
sizeof (data_rcvd) ) 


printf("Please enter your 
"indicates that you 


gets (inbuf); ea 
reply_len = strlen(inbuf); 
while (reply_len != 0) /* 


{ 

memcpy (send_buffer, inb 

QNMSNDRP (&appl_handle 
énotif_recor 
&send_buffer 
&reply_len, 
é&reply_inc, 
&no_wait, 


P/MSTDTAQ) MAXLEN(80)"); /* 


Create data queue */ 
Start application */ 
Check error code af 
Register the application */ 
Check error code * fs 
ta; 


Loop until an ending string 

has been sent by the requesting 
application Hof 
eue_name, 

name, 


Receive indication from data 
queue 


xf 


) /* Incoming data was 

received? i: 

data, 

/* Null out the 
*/ 


ceived_data)); 
receive buffer 


i 


/* Receive data using the 
request ID in the notification*/ 


/* Check error code aay 
r.received_data); /* Display 
the received data */ 
== 0) /* Request requires 
a reply? */ 
replies (a null line " 
are finished) \n"); /* Display 
a prompt message af 
Get the reply data */ 
/* Get length of reply */ 
While no null string was input 
a 
uf, strlen(inbuf)); /* Copy 
data to send buffer */ 


v 
d.req_id, 


£ 


é&error_code_struc); /* Send a reply to the 
source application (specify 
"not last" reply). The results 
of this operation will be 
obtained later using the 
receive operation completion 
API. A; 
gets (inbuf) ; /* Get the next reply * / 
reply_len = strlen(inbuf); /* Get length of reply * / 
} 
QNMSNDRP (&appl_handle, 

énotif_record.req_id, 

&send_buffer, 

&reply_len, 

&reply_cmp, 

&éno_wait, 

é&error_code_struc); /* Send final reply (this 
contains no data). The results 
of this operation will be 
obtained later using the 
receive operation completion 


API. */ 
} 
else 
{ /* A reply is not required *y: 
if (memcmp (data_revd, 
REQUEST, 
sizeof (data_rcevd)) != 0) /* Something other than a 
request was received? */ 
{ 
printf ("Incorrect data was received, " 
"data_rcvd = %1.10s\n", data_revd); /* Print 
value of data_rcvd aay 
} 
} 
} 
else 
{ /* A send completion was received 
for a previous send reply 
operation ef 


QNMRCVOC (&appl_handle, 
énotif_record.req_id, 
&qual_appl, 
é&error_code_struc);/* Receive operation completion*/ 


check_error_code ("QNMRCVOC"); /* Check error code */ 
printf ("Reply was sent successfully.\n"); /* Error code was 
OK */; 


} 


QNMDRGAP (é&appl_handle, 


&error_code_struc) ; /* Deregister the application mf, 

QNMENDAP (&appl_handle, 
é&error_code_struc); /* End the application */ 

return 0; 

*/ 
check_error_code - */ 
bays 
This function validates the error code parameter returned on * 
the call to a management services transport API program. If ef 
an error occurred, it displays the error that occurred and */ 
ends this program. * 
HA 


void check_error_code (char func_name [8] ) 


{ 
char *sense_ptr = error_code_struc.exception_data + 36; /* 
Pointer to sense code in 


exception data *Y 
SENSECODE sense_code; /* SNA sense code */ 
if (error_code_struc.bytes_available != 0) /* Error occurred? */ 


{ 
printf ("\nError occurred calling %1.8s.\n", func_name) ; 
memcpy (sense_code, 
sense_ptr, 
sizeof (sense_code) ); /* Copy sense code from exception 
data a, 
printf("Error code is %1.7s, SNA sense code is %1.8s.\n", 
error_code_struc.exception_ID, 
sense_code); 
if (memcmp (func_name, 


"QNMSTRAP", 
sizeof ("QNMSTRAP")) != 0) /* Error did not occur on 
start application? mf 
{ 
QNMENDAP (&appl_handle, 
é&error_code_struc); /* End the application */ 
} 
exit (EXIT_FAILURE) ; /* Exit this program */ 


Using Source Debugger APIs 


The ILE source debugger APIs allow an application developer to write a debugger for ILE programs. One might ask why this would 
ever be done when an ILE debugger is provided with OS/400. There are several reasons why an application developer might want to 
use these APIs to write a different ILE debugger: 


e A debugger running on a workstation could be built that would debug ILE programs running on the iSeries server. This 
would allow a debugger to be written that would take advantage of Windows and other ease-of-use interfaces available on the 
workstation. The workstation debugger would communicate with code running on the iSeries server. The code running on the 
iSeries server would use the debugger APIs. 


e The writer of an ILE compiler on the iSeries server might want to write a debugger to take advantages of the features of the 
language. The OS/400 debugger is a more general-purpose debugger made for all ILE languages. 


e A debugger could be written with functions not available on the OS/400 ILE debugger. 


Source Debugger APIs--Overview 


The ILE source debugger APIs can be divided into several groups. These include APIs that: 


e Start and end the debug session 
e Add programs and modules to debug 
e Manipulate text views in a program 


e Add and remove breakpoints, steps, and so on 


Besides APIs, there are two user exits that get called: 


e@ The Source Debug program gets called when the Start Debug (STRDBG), Display Module Source (DSPMODSRC), and End 
Debug (ENDDBG) CL commands are entered. 


e@ The Program Stop Handler gets called when an ILE program being debugged hits a breakpoint, step, and so on. 


To demonstrate how these APIs are used, this topic presents an example debugger with complete code examples and an explanation 
of what the APIs do. 


The ILE debugger that comes with OS/400 uses the debugger APIs just as a user-written debugger would. There is nothing special 
about the OS/400 debugger. Its functions could be done by an application developer using the debugger APIs and other OS/400 APIs. 


A Simple Debugger--Scenario 
Consider a simple scenario in which the user wishes to debug an ILE program. 
1. From the command entry screen, the user enters the Start Debug (STRDBG) command, passing it the name of an ILE 
program to debug. 
STRDBG Pl 
2. The ILE debugger screen is displayed, showing the source of a module in the ILE program being debugged. From this screen, 
the user adds a breakpoint and then exits. 
3. Back at the command entry screen, the user runs the ILE program that is being debugged. 
CALL Pl 
4. The ILE program hits the breakpoint previously set. The ILE debugger screen is displayed, highlighting in the source where 
the program has stopped at the breakpoint. 
5. The user displays a variable in the program being debugged. 
6. The user exits the ILE debugger, allowing the ILE program to run to completion. The program ends. 


7. Back at the command entry screen, the user ends the debug session. 


ENDDBG 
This is the simplest of debug scenarios, but it illustrates how OS/400, the debugger user exits, and the debugger APIs interact. 


The following figure shows the various interactions. 
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A detailed explanation of the scenario follows: 


1. The Start Debug (STRDBG) CL command is used to start the debug session. By default, if an ILE program is specified on 
the command, the OS/400 ILE debugger user exit is called. A different user exit (called the Source Debug program) can be 
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specified on the Start Debug command by specifying a program name on the SRCDBGPGM parameter. 


When the Source Debug program is called, it is passed a reason field, which indicates why it was called. The *START reason 
is passed to it by the Start Debug command, indicating that the ILE debugger is to start itself and do any necessary 
initialization. When the *START reason is indicated, the names of any ILE programs on the Start Debug command are also 
passed to the Source Debug program. 


. In this scenario, the system Source Debug program initializes itself. It calls the QteStartSourceDebug API, which tells the 
system that ILE debugging is to be done. The name of a program stop handler program is passed to this API. The stop 
handler is a program that the system calls when an ILE program hits a breakpoint, step, or other condition where the system 
stops the program for the debugger. 


The Source Debug program must indicate to the system that the ILE programs specified on the Start Debug command are to 
be debugged. To do this, the QteRetrieveModuleViews API is called, once for each ILE program specified on the Start 
Debug command. In this scenario, the API is called, passing it the name of program P1. The purpose of the API is to return 
information about the ILE program, including the modules and views of the program. A view is the source text that is 
displayed by the debugger for a particular module. 


Once information about the ILE program is obtained, one or more views of the program must be registered. Once a view is 
registered, the system can perform various functions on that view in behalf of the debugger application. For performance 
reasons, only the views the user is interested in displaying should be registered. 


The Source Debug program is now done performing the function for the *START reason. It exits, returning control to the 
Start Debug command. 


. By default, if an ILE program is specified on the Start Debug command, the ILE debug screen is displayed. To indicate to the 
ILE debugger that a screen is to be put up, the Source Debug program is called by the command again, this time with a 
reason of *DISPLAY. 


Because this is the first time any views for P1 are to be displayed, the ILE debugger must retrieve the text to display. The 
first view of the first module of the program is selected as the default view to display. 


The Source Debug program calls the QteRetrieve ViewText API to retrieve the text associated with the default view. Next, in 
case this program is already on the stack and stopped, the QteRetrieveStoppedPosition API is called to check. If the program 
were on the stack, the source would be positioned to the statement where the program was stopped, and that line would be 
highlighted. In this scenario, the program is not yet on the stack, so the first line of the source will appear at the top of the 
screen, and no line will be highlighted. 


The Source Debug program next calls User Interface Manager (UIM) APIs to display the source on the screen. 


. At this point, the source screen is displayed showing the text of the first view in the first module of the first ILE program 
specified on the Start Debug command. From this screen, the user can enter debug commands or do other options provided 
by the debugger application. 


In this scenario, the user adds a breakpoint to a line in the ILE program P1 being debugged. When a command is entered, the 
UIM APIs call a program which is part of the ILE debugger to process the command. 


To process the breakpoint, the QteAddBreakpoint is called. It is passed a view number which indicates the view being 
displayed, and a line number in that view. A breakpoint is added to the program by the API. 


. Back to the UIM screen, the user exits the ILE debugger. Once at the command entry screen, the user then runs the program 
P1 which has the breakpoint. 


. When PI hits the breakpoint, the system calls the program stop handler defined by the QteStartSourceDebug API. The 
Program Stop Handler calls UIM to put up the source for the module where the program has stopped because of the 
breakpoint. The line is highlighted to show the user exactly where the program has stopped. 


. From the source debugger screen, the user displays a variable in program P1 which is stopped at the breakpoint. UIM calls 
the debugger to process the command. The debugger calls the QteSubmitDebugCommand API, which retrieves the value of 
the variable to be displayed. The debugger then displays this value on the screen. 


. The user now exits from the source debugger screen. This allows P1, which was stopped at a breakpoint, to continue running. 
When P1 ends, the user is back at the command entry screen. 


. The user ends the debug session by entering the End Debug (ENDDBG) CL command. The system calls the Source Debug 
program, passing it a reason of *STOP. The Source Debug program calls the QteEndSourceDebug API to indicate to the 
system that ILE debugging has ended. It then tears down its own environment (closes files, frees space, and so on) and then 
ends. The End Debug command completes, and the user is back to the command entry, the debug session having ended. 


Source Debugger--Example 


This section discusses an example ILE debugger that demonstrates the use of some of the ILE debugger APIs. Each function in the C 
program is discussed along with the APIs that they call. Although the entire program listing is printed later (see Debugger 


Code--Sample), each function or piece of code is printed with the section where it is discussed to make reading the code easier. 


The example debugger does not use all ILE debugger APIs. Its function is limited. After the discussion of the code, the APIs and 
some functions not covered are discussed. 


Compiling the Debugger 

The Create C Module (CRTCMOD) command compiles the source code of the debugger. It is compiled into module DEBUG. 

The Create Program (CRTPGM) command creates program DEBUG from module DEBUG. It is necessary to bind to service 
program QTEDBGS so that the calls to the debugger APIs are resolved. It is also important to use activation group QTEDBGAG. 
This is an activation group that cannot be destroyed while the job is in debug mode. Thus, all static variables in program DEBUG 
remain intact throughout the debugging of the ILE program. Only when ENDDBG is entered can the activation group be destroyed, 
even if the Reclaim Resources (RCLRSC) CL command is entered. 

Starting the Debugger 

The example debugger consists of a single program called DEBUG. The program is used as the Source Debug program as well as the 
Program Stop Handler. The program determines how many parameters it is being called with, and with this information it does the 


function of one or the other of the user exits. 


The debugger can debug only one ILE program. This program is specified on the Start Debug CL command. The program cannot be 
removed from debug until ENDDBG is done. No new programs can be added. 


To debug an ILE program P1 with this sample debugger, the following CL command could be entered: 


STRDBG P1l SRCDBGPGM (DEBUG) 
Note that DEBUG must be in the library list when STRDBG is done. 


If the command is done, P1 is called twice, once as a Source Debug program given a reason of *START, and again as a Source 
Debug program given a reason of *DISPLAY. 


Other variations of the Start Debug command can be given with different results. For example, the following CL command causes 
DEBUG to be called only once with a reason of *START: 


STRDBG P1 SRCDBGPGM(DEBUG) DSPMODSRC (*NO) 


This is because STRDBG has been told not to display the debug screen, so the *DISPLAY reason is not given until the user does the 
Display Module Source (DSPMODSRC) CL command. 


The following example does not even call DEBUGGER: 


STRDBG SRCDBGPGM (DEBUG) 

This is because no ILE program is specified. If an ILE program receives an unmonitored message and the ILE debugger needs to be 
called, DEBUG is first called with *START as a Source Debug program. Also, if Display Module Source is entered, the *START 
and then the *DISPLAY reason is passed to DEBUG. 

Using the Debugger 


When the debugger is started, it allows simple debugging commands to be entered. The C session manager is put up, which scrolls 
the users commands and the debugger output. To see a list of the allowable commands, enter HELP. 


The "list views" command shows all of the views available in the program being debugged. The text description of the view is listed, 
with a sequential number. This number is used by the "switch" command to switch to that view. 


The "list text" command prints out the text of the current view. Text has a line number next to it. The line number is used when 
setting breakpoints or other debug commands. 


The switch command switches the current view. The current view is the view used when setting breakpoints, displaying variables, 


viewing text, and so on. 
The "quit" command exits the debugger. 


Other commands are interpreted by the QteSubmitDebugCommand API. This API will be discussed later. An example command that 
can be entered is "break n", where n is the line number in the current view. These commands are similar to the ones allowed in the 
ILE debugger shipped with OS/400. 


Header Files Used in Debugger 


#include <stdio.h> 

#include <string.h> 
#include <stdlib.h> 
#include <qtedbgs.h> 


Besides the normal C library header files, an API header file, qtedbgs.h is included. This file defines the functions exported from 
service program QTEDBGS. This service program contains the ILE debugger APIs. 


Global Variables 

static _TE_VEWL0100_T *pgm_dbg_dta = NULL; 

static long current_view = 0; /* current view —- defaults to l1st*/ 
static _TE_OBJLIB_T program_lib; /* name and lib of pgm debugged */ 


These are global variables that hold information about the program being debugged. These variables do not go away when program 
DEBUG exits, because they are stored in the activation group which is not destroyed until the debug session has completed. 


The name and library of the program are stored, as is the current view being debugged. Also, a pointer to a structure returned by the 
QteRetrieveModuleViews is saved, as this information is needed when debugging the various views of the program. 


PgmList_t 


typedef struct { 

TE_OBJLIB_T PgmLib; /* Name and Library of program bays 
_TE_NAME_T PgmType; /* program type, *PGM or *SRVPGM */ 
} PgmList_t; 


This is the structure of the name, library, and type of the program being debugged. 


main() 


main (int argc, char *argv[]) { 
if (argc == 4) /* called as source debug program*/ 
HandleSession(argv[1], (PgmList_t *)argv[2], *(int 
*)argv[3]); 
else if (argc == 8) /* called as program stop handler*/ 
HandleStop((_TE_OBJLIB_T *)argv[1], argv[2], 
argv[3], argv[4], 
(long *)argv[5], *(int *)argv[6]l, 
argv[7]); 
} 


Program DEBUG can be called in two ways. When it is called by the STRDBG, DSPMODSRC, and ENDDBG CL commands, it is 
called as the Source Debug program user exit. It is passed three parameters. 


DEBUG can also be called when a program being debug hits a breakpoint or step. In this case, it is passed seven parameters. 


DEBUG therefore can determine why it was called by counting the number of parameters it was passed. Remember that argc includes 
the program name as the first argument passed. 


If argc is 4 (three parameters passed to DEBUG), function HandleSession is called, and the three parameters passed to DEBUG are 
passed to it, typecasted as needed. 


If argc is 8 (seven parameters passed to DEBUG), function HandleStop is called, and the seven parameters passed to DEBUG are 
passed to it, typecasted as needed. 


If any other number of parameters are passed to DEBUG, it cannot have been called from the OS/400 debug support, so DEBUG will 
just exit. 


HandleSession() 


void HandleSession(char reason[10], 
PgmList_t ProgramList[], 
int ProgramListCount) { 


if (memcmp (reason, "*START ",10) == 0) /* reason is *START */ 
StartUpDebugger (ProgramList, ProgramListCount) ; 

else if ( memcmp (reason, "*STOP ",10) == 0) /* reason is *STOP */ 
TearDownDebugger () ; 

else if ( memcmp(reason,"*DISPLAY ",10) == 0) /* reason *DISPLAY */ 


ProcessCommands () ; 


} 


When DEBUG is called as a session handler, it is passed three parameters. The first parameter is a 10-character array containing a 
reason field. This contains the reason why the session handler is called. 


When DEBUG is first called, it is passed a reason of *START, indicating that the debugger is to initialize for an ILE debug session. 
When this reason is given, the second parameter contains a list of ILE programs specified on the STRDBG command, and the third 
parameter contains the number of programs specified on parameter two. From 0 to 10 ILE programs can be specified. 


When the user wishes to see the ILE debugger screen, either from STRDBG or DSPMODSRC, a reason of *DISPLAY is passed. 
When the user enters ENDDBG, the *STOP reason is passed, indicating that the ILE debug session is ending. The second and third 
parameters are not used when the reason is *DISPLAY or *STOP. 


The code tests for a reason and calls the appropriate function. There is one function for each reason that can be passed. 


TearDownDebugger() 


void TearDownDebugger(void) { 
TE_ERROR_CODE_T errorCode = {8}; /* errors will be ignored */ 


/* Call EndSourceDebug to get out of ILE debug mode */ 
QteEndSourceDebug (&errorCode) ; 


exit (0); /* destroy activation group ays 


} 


This function is called when the user enters ENDDBG. The debugger calls the QteEndSourceDebug API which ends ILE debugging. 
Since an 8 is passed as the number of bytes provided, the message ID and error data from an error are not returned to the caller. Thus, 
any errors from this API (there should not be any) are ignored. 


The exit() function is called, which destroys the activation group. Thus, all global data defined in the program's variables are lost. 
This is ok, since the debug session is ending at this point. 


StartUpDebugger() 


void StartUpDebugger (PgmList_t ProgramList[], 
int ProgramListCount) { 


_TE_ERROR_CODE_T errorCode = {0}; /* exceptions are generated */ 

_TE_OBJLIB_T StopHandler = {"DEBUG wo W*ETBL Wy 

int 1; 

if (ProgramListCount!=1) { /* is only 1 pgm passed on STRDBG*/ 
printf ("Exactly ONE program must be specified on STRDBG.\n"); 
TearDownDebugger () ; /* end debugger */ 

} 

/* Copy program name to global variables */ 


memcpy (&program_lib, &ProgramList-—>PgmLib, 20); 


/* Call StartSourceDebug: giving the name and library of the *y 
/* stop handler. This will start ILE debug mode */ 


QteStartSourceDebug(&StopHandler, &errorCode) ; 


AddProgram() ; /* add program to debug fp 
} 


This function is passed the second and third parameters which were passed from the system when it called DEBUG with a reason of 
*START. These parameters are the list of programs to be added to debug and the number of programs in the list. This simple 
example debugger can only debug one program, so if any other number of programs were specified on STRDBG, the debugger just 
exits. 


StartUpDebugger first stores the program/library element passed to it in a global variable available to all functions. This is the name 
and library of the program being debugged. It then calls the QteStartSourceDebug API to tell the system that an ILE debug session is 
to begin. The name and library of program DEBUG are passed to this API as the Program Stop Handler. Thus, whenever the program 
being debugged is stopped by the debugger, program DEBUG will be called. 

Finally, the function calls AddProgram to add the single program to debug. 


AddProgram() 


void AddProgram(void) { 


TE_ERROR_CODE_T errorCode = {0}; /* Signal exceptions on error */ 
_TE_NAME_ Library; /* Lib returned */ 
_TE_TIMESTAMP_T TimeStamp; /* TimeStamp returned */ 
int viewIndex; 
long int iViewID; 
long int iViewLines; 
long rtvModViewDataLength = 8; /* size of receiver buffer */ 
char tempBuffer[8]; /* enough room for header only*/ 


int i, tempModuleCount; 


/* Call QteRetrieveModuleViews to determine the number of bytes */ 
/* the receiver variable needs to be to hold all of the views for */ 
/* the program. mf 
pgm_dbg_dta = (_TE_VEWLO100_T *)tempBuffer; 


QteRetrieveModuleViews ((char *)pgm_dbg_dta, &rtvModViewDataLength, 
"VEWLO100", &program_lib, 
"*PGM ") "*ALL ", Library, 
&errorCode) ; 


/* Get a buffer large enough to hold all view information */ 
rtvModViewDataLength = pgm_dbg_dta->BytesAvailable; 
pgm_dbg_dta = (_TE_VEWLO0100_T *)malloc(rtvModViewDataLength) ; 


/* Call QteRetrieveModuleViews again, passing a big enough buffer. */ 
QteRetrieveModuleViews((char *)pgm_dbg_dta, &rtvModViewDataLength, 
"VEWLO100", &program_lib, 
"*PGM ") "*ALL ", Library, 
&errorCode) ; 


/* If number of elements is zero, program is not debuggable. */ 
if (pgm_dbg_dta->NumberElements == 0) { 
printf("Program %.10s in Library %.10s cannot be debugged.", 
program_lib.obj, program_lib.1lib); 
TearDownDebugger () ; 


} 


/* Put the library returned by Retrieve Module Views in PgmLib * / 
memcpy (program_lib.lib, Library, sizeof (_TE_NAME_T)); 


/* Register all views in the program */ 
for (i=0; i < pgm_dbg_dta->NumberElements; itt) { 
QteRegisterDebugView(&iViewID, &iViewLines, Library, TimeStamp, 
éprogram_lib, "*PGM wee 
pgm_dbg_dta->Element [i] .ModuleName, 
épgm_dbg_dta-—>Element [i] .ViewNumber, 
&errorCode) ; 


/* overwrite unneeded ViewNumber with obtained view id */ 
pgm_dbg_dta->Element [i].ViewNumber = iViewID; 
} 
} 


The heart of this function is the two calls to the QteRetrieveModuleViews API and the call to QteRegisterDebug View API. 


The QteRetrieveModuleViews API returns information about an ILE program. It returns this information in a structure of type 
_TE_VEWL0100_T. This is a fairly complex structure that has the following fields: 


typedef _Packed struct { /* format VEWLO100 */ 
long int BytesReturned; /* number of bytes returned */ 
long int BytesAvailable; /* number of bytes available x, 
long int NumberElements; /* number of elements returned iA 
_Packed struct { /* one element */ 
_TE_NAME_T ModuleName; /* name of module in program an 
_TE_NAME_T ViewType; /* type of view: mf 
_TE_COMPILER_ID_T CompilerID; /* compiler ID */ 
_TE_NAME_T MainIndicator; /* main indicator */ 
_TE_TIMESTAMP_T TimeStamp; /* time view was created */ 
_TE_TEXTDESC_T ViewDescription; /* view description af 
char Reserved[3]; 
long int ViewNumber; /* view number within module ays 
long int NumViews; /* number of views in this module*/ 
} Element [1]; /* one element */ 


} _TE_VEWLO100_T; 


This structure has a header portion which holds the number of bytes returned by the API (BytesReturned), the number of bytes that 
can be returned by the API, used when there is not enough room for the API to return all of its data (BytesAvailable), and the number 
of elements (views) returned by the API (NumberElements). 


Since there is no way to know in advance how many views a program has, the QteRetrieveModuleViews API should be called once 
with only enough storage to return the number of bytes that the API needs to return all of its information. Thus, the first call to the 
API provides only 8 bytes of storage for the API to return its data. This allows the API to fill in the BytesAvailable field. 


QteRetrieveModule Views is passed a buffer to hold the receiver variable and the length of that buffer (in this case, 8 bytes). It is also 
passed a format name which identifies the structure of the receiver variable. The only allowable format name at this time is 
VEWLO100. A structure containing the program name and library name of the ILE program is passed. Also, the program type is 
passed. In this example debugger, only *PGM objects can be debugged, but it is possible to debug *SRVPGM objects using the ILE 
debugger APIs. 


The name of the module is provided, in which case information about that module is returned. *ALL indicates that information about 
all modules in the program is to be returned. A return library variable is passed. This is so that when *LIBL is passed as a library 
name, the real library name can be obtained, making subsequent API calls faster because the library list won't have to be searched 
again. 


Finally an error code structure is passed to the API. This structure is initialized with a zero, indicating that the API is not to fill in any 
error code data. Instead, the API issues an exception if an error occurs. No errors are expected, so this should not matter. 


Before QteRetrieveModuleViews is called again, a buffer large enough to hold all of the information is created. The API is called 
again with the same parameters, but this time the entire information will be stored by the API in the allocated buffer. 


If the API does not return any elements, this means that none of the modules has debug data. In this case, the program cannot be 
debugged, so the debug session is ended. 


Now that a list of views has been retrieved, it is time to register all of the views to the system, making it possible to do debug 
operations against them. In a real debugger, only the views requested to be seen by the user would be registered to save processing 
time, but in this example, all views will be registered at once. 


Not all of the fields in the VEWLOLO00 structure are needed by this debugger. However, they will be described here. The API returns 
one element for each view in the program. Each module in the program may have several views. All views for a particular module are 
contiguous in the list. 


ModuleName This is the name of the module in the program which this particular view is for. 


ViewType This indicates the type of view. A *TEXT view contains text retrieved from source files residing on the iSeries 
server. The text contains sequence information from these files that the debugger may not want to display. A 
*LISTING view contains text that is stored with the program object itself. A *STATEMENT view contains 
information about HLL statements in the module, and this information is not generally displayed to the user but 
is used by the debugger. In the case of this debugger, all views are displayed exactly as the text for the views are 
retrieved. 


CompilerID This indicates the language that the particular module is written in. This is not used by the example debugger. 


MainIndicator Only one module in a program is the module with the program entry procedure (main() in the case of ILE C 
programs). If a particular view in the list comes from this module, then this field indicates that the module 
contains this procedure. This field is not used by the example debugger. 


TimeStamp This indicates when the view was created. This is useful in allowing the debugger to detect if a program has been 
recompiled and the debugger has down-level view information. This field is not used by the example debugger. 


ViewDescription This is text given to the view by the compiler creating the view. It is a description of the view which can be 
displayed by the debugger. 


ViewNumber This is a sequence number of the view in a particular module. When registering a view, the program name, 
module name, and view number must be provided. 


NumViews This is how many views are in the module. All elements for views in a given module have the same value for this 
field. This field is not used by the example debugger. 


A loop through all the views returned by QteRetrieveModule Views is done, registering the view using the QteRegisterDebug View 
API. The program name, program type, module name, and view number of the module are passed as inputs to the API. The API 
returns the library of the program (in case *LIBL) is passed in as the program library), the timestamp of the view (in case the program 
has been recompiled between the time the view information was retrieved and the time the view was registered), the number of lines 
of text in the view, and a view ID. The view ID is a handle, and it is used in identifying the registered view to various APIs. For 
example, when retrieving text for a particular view, the view must be registered, and the view ID returned when registering the view 
is passed to the QteRetrieveViewText API. 


The structure that held the views retrieved by QteRetrieveModuleViews is also used by the debugger. The view number is no longer 
needed, since it is just a sequence number passed to QteRegisterDebug View. Thus, this number is overwritten and will hold the view 
ID, which is needed by other debugger APIs. 


ProcessCommands() 


void ProcessCommands (void) { 
char InputBuffer[80]; 
char *token; 


int i; 
int step=0; /* do an exit for step when 1 */ 
if (pgm_dbg_dta == NULL) { /* if no debug data */ 
printf("Debug session has ended.\n"); 
exit (0); /* end the debugger */ 
} 
while(!step) { /* read until step or quit cmd ay: 
ReadLine (InputBuffer, sizeof (InputBuffer) ); 
token = strtok(InputBuffer," "); 
if (token==NULL) continue; /* ignore blank lines */ 
else if (stremp(token,"quit") == 0) /* the quit command? */ 
return; /* exit debugger */ 
else if (stremp(token,"list") == 0) /* the list command? */ 
ProcessListCommand() ; /* process command */ 
else if (strcemp(token,"switch") == 0) { /* switch command? */ 
token = strtok(NULL," "); /* get view number token */ 
if (token == NULL) 
printf(""'switch' must be followed by a view number.\n"); 
else 
current_view = atoi(token) ; /* switch current view */ 
} 
else if (strcemp(token,"help") == 0) { 
printf("The following are the allowed debugger commands:\n"); 
printf(" list views —- lists all views in the program\n"); 
printf(" list text - lists the text of the current view\n"); 


printf(" switch n - changes current view to view n\n"); 
printf(" help - displays this help text\n"); 
printf(" quit - ends the debug session\n"); 
printf ("Other commands are interpreted by the debug support.\n"); 
} 
else { /* pass command to API * / 
/* Undo modifications that strtok did */ 
InputBuffer[strlen(InputBuffer)] = ' '; 


step = ProcessDbgCommand(InputBuffer) ; 
} 


} 


This function reads an input line from the user and processes it. If it is a command recognized by the debugger, it process it. If not, it 
calls ProcessDebugCommand which lets QteSubmitDebugCommand process the command. 


The first test is to make sure that the pointer to the debug data is not null. This is here for safety reasons. If program DEBUG is 
compiled with the wrong activation group name or no name at all, its global variables can be destroyed when the program exits, 
causing problems when the program is called again. This test prevents debug commands from being entered if the activation group 
has been destroyed, wiping out the global view data. 


The function loops until the quit command is entered or until a step is done. It calls the appropriate function based on the command 
entered, or displays an error message if a syntax error is detected. If the command is unknown, it is processed by 
ProcessDbgCommand. 


The switch command is processed directly by the function. It changes the current view to a number provided. There is no error 
checking in this sample debugger. 


ReadLine() 


void ReadLine(char *Buffer, int length) { 
inti /* loop counter ae A 


printf ("Enter a debugger command or ‘'help'.\n"); 


fgets (Buffer, length, stdin) ; /* read line of text bans 
/* Blank out line from \n to the end of the string. */ 
for (i=0; i<length; i++) { /* loop, searching for newline * f: 
if (Buffer[i] == '\n') { /* if newline character found 
*/ 
break; /* end loop searching for newline*/ 
} 
} 
memset (Buffert+ti,' ',length-i); /* blank remainder of line */ 


} 
This function reads a line of text from the user and fills the input buffer with trailing blanks. 


ProcessList Command() 


void ProcessListCommand(void) { 


char *token; /* pointer to next token of input*/ 

token = strtok(NULL," "); /* get next token in input buffer*/ 

if (token==NULL) /* list not followed by anything */ 
printf("'list' must be followed by 'views' or 'text'.\n"); 

else if (strcmp (token,"views") == 0)/* if list views */ 
PrintViews (); 

else if (strcemp(token,"text") == 0) /* if list text */ 
PrintText (); 

else /* list <something-else> Bef, 


printf("'list' must be followed by 'views' or 'text'.\n"); 


This routine process the list command. There are two versions of the list command, list views and list text. The appropriate function 
is called depending on the type of list command entered, or a syntax error message is issued. 


Print Views 


void PrintViews (void) { 
int k; 


/* loop through views printing view#, module, and view desc. text */ 
for (k=0; k< pgm_dbg_dta-—>NumberElements; k++) { 

printf("Sd) %.10s:%.50s", 

k, 
pgm_dbg_dta-—>Element [k] .ModuleName, 
pgm_dbg_dta->Element [k] .ViewDescription) ; 

if (current_view == k) /* indicate if view is current */ 

printf ("<---Current\n"); 
else 

printf ("\n"); 


} 


This routine lists all of the views available in the program being debugged. The information about the views is stored in the buffer 
that was passed to QteRetrieveModuleViews. 


The module name and view descriptive text is printed for each view. If the current view being printed is also the current view, this is 
noted by printing this fact next to the view information. 


A view number is printed next to each view. This is not the view ID returned by the QteRegisterDebug View. It is a number allowing 
the user to change the current view to one of the views in the list. 


PrintText() 


void PrintText (void) { 


long LineLength = 92; /* length of lines of text */ 
long NumberOfLines = 0; /* lines to retrieve - 0 = all */ 
long StartLine=1; /* retrieve from line 1 (first) */ 
long bufferLength = 100000; /* size of retrieved text buffer */ 
long viewID; /* view ID of text to retrieve bard 
_TE_TEXT_BUFFER_T *buffer; /* text retrieved by API */ 
_TE_ERROR_CODE_T errorCode = {0}; /* Exceptions will be signaled * / 
int: ay /* points to start of each line */ 
int line_number; /* line number counter for loop */ 
/* Get View ID of current view * / 


viewID = pgm_dbg_dta->Element [current_view] .ViewNumber; 
buffer = malloc (bufferLength) ; /* malloc space for big text buf */ 


/* Call Retrieve_View_Text for the current view. */ 

QteRetrieveViewText ((char *)buffer, &bufferLength, &viewlID, 
éStartLine, &NumberOfLines, &LineLength, 
&errorCode) ; 


/* Print out the text */ 
for (i=0,line_number=1; 
line_number <= buffer->NumLines; 
line_number++,it+=LineLength) { 
printf ("%3d) %.70s\n", line_number, buffer->Text+i) ; 


} 


free (buffer) ; /* free memory for buffer */ 


} 


This function retrieves the text associated with the current view and prints it. This text is the source of the program and is the heart of 
a source debugger screen. 


The text of the current view is retrieved, so the view ID of that view is determined. It is this view that is passed to 
QteRetrieveViewText. 


In the sample debugger, a large buffer is allocated, and as much text as will fit in this buffer is retrieved. The QteRetrieveViewText 
API returns the text and the number of lines that fit in the buffer. 


Once the text is retrieved, it is printed out along with the line number. The line number is needed when setting breakpoints based on 
the view. 


ProcessDbgCommand() 


int ProcessDbgCommand(char InputBuffer[80]) { 
_TE_ERROR_CODE_T errorCode = {64}; /* fill in bytes provided */ 
char OutputBuffer[4096]; 
struct _TE_RESULT_BUFFER_T *Results; 
long InputBufferLength = 80; 
long OutputBufferLength = sizeof (OutputBuffer) ; 
long view_ID; 
_TE_COMPILER_ID_T *CompilerID; 
int i; 
int return_value = 0; 


view_ID = pgm_dbg_dta->Element [current_view] .ViewNumber; 
CompilerID = &pgm_dbg_dta-—>Element [current_view] .CompilerID; 


/* Give command to QteSubmitDebugCommand */ 
QteSubmitDebugCommand(OutputBuffer, &OutputBufferLength, 
é&view_ID, InputBuffer, &InputBufferLength, 
*CompilerID, &errorCode) ; 


if (errorCode.BytesAvailable != 0) { 
printf("Error = %.7s\n",errorCode.ExceptionID) ; 


return return_value; 


} 


/* Process results from QteSubmitDebugCommand ay 
Results = (_TE_RESULT_BUFFER_T *) OutputBuffer; 
/* Loop through Results array */ 


for (i=0; i<Results-—>Header.EntryCount; itt) { 
switch (Results-—>Data[i] .ResultKind) 
{ 
case _TE_kStepR 
printf ("Step set\n"); 
return_value=1; /* indicate step is to be done af 
break; 
case _TE_kBreakR : 
printf ("Breakpoint set"); 
break; 
case _TE_kBreakPositionR 
printf(" at line %d\n", 
Results->Data[i].V.BreakPosition.Line) ; 


break; 
case _TE_kExpressionTextR 
printf ("%s" 
((char *)Results) + Results-—>Data[i].V. 
ExpressionText.oExpressionText) ; 
break; 
case _TE_kExpressionValueR 
printf(" = %s\n", 
((char *)Results) + Results-—>Data[i].V. 
ExpressionValue.oExpressionValue) ; 
break; 
case _TE_kQualifyR 
printf ("Qual set\n"); 
break; 


case _TE_kClearBreakpointR 


printf ("Breakpoint cleared\n"); 
break; 

case _TE_kClearPgmR 
printf ("All breakpoints cleared\n"); 


break; 
default: /* ignore all other record types */ 
break; 
} /* switch */ 
} /* loop through results array ey: 


return return_value; 


} 


This function is called to process all commands not known by the debugger. It calls the QteSubmitDebugCommand API which is 
passed a view ID, compiler ID, and a command. The API needs the compiler ID because each programming language used in 
compiling a particular module has different debug commands or command syntax, and the API needs to know which language was 
used when compiling the module. 


The API returns back a series of result records which indicate what was done by the API. Most of this function reads the results of the 
records returned and prints an appropriate response message. 


Some results records indicate that a particular function has been performed. These include: 


_TE_kStepR The step command was successfully done. 
_TE_kBreakR The break command was successfully done. 
_TE_kQualifyR The qual command was successfully done. 


_TE_kClearBreakpointR The clear breakpoint command was successfully done. 


_TE_kClearPgmR The clear pgm command was successfully done. 


Other results records contain numeric data useful by the debugger. 


_TE_kBreakPositionR Contains the line number where a breakpoint was set. It is possible that a breakpoint set on two different 
lines will correspond to the same HLL statement. In this case, only one breakpoint is really set. To 
determine if this is the case, it is necessary to map the position in the view where the breakpoint is set to a 
position in the statement view. 


Still other results records contain string data. In this case, the record contains an offset into the string space returned by the API as 
well as a string length. 
_TE_kExpressionTextR This points to the expression entered in the eval command. 


_TE_kExpressionValueR This points to the value of the evaluated expression. 


There are other kinds of results records than processed by the sample debugger. The QteSubmitDebugCommand API discusses in 
detail each result record and the data it contains. 


The API description also discusses the syntax of the debug command that must be passed to it. The commands and their syntax will 
not be discussed in depth here, but a few example commands will be shown: 
e break 5 when x == 
This is a conditional breakpoint. The debugger will stop the program indicated by the view ID passed to the API when it 


reaches line 5 of the view and when the expression "x == 3" is true. The "when" part of the break statement is optional, in 
which case an unconditional breakpoint is set. 


e step | into 
The step command instructs the debug support to stop the a program when it has executed one or more statements. In this 
example, the program is stopped after 1 statement has been executed. The "into" means that statements in procedures are 


counted when stepping. "over" means that statements in called procedures are skipped over and not counted. The default step 
type is "into", and the default step count is 1. 


e qual 13 


The qual command is necessary when there are blocks of code with the same variable name. In this case, the user indicates 
where the variable is searched for in the program. Normally, this command is not used. 


e clear 8 


A conditional or unconditional breakpoint is removed from line 8 of the view indicated by the view ID parameter. 


HandleStop() 


void HandleStop(_TE_OBJLIB_T *ProgramLib, 
E_NAME_T ProgramType, 
_TE_NAME_T Module, 

char reason[10], 

long Statements[], 

int StatementsCount, 


char *message) { 


int i; 

_TE_MAPP0100_T Map_Return_Structure; 

long Column = 1; 

long MapLength = sizeof (Map_Return_Structure) ; 
_TE_ERROR_CODE_T errorCode = {64}; 

long stmt_view; 


/* If current view is for a different module than the one that is */ 
/* stopped, change current view to first view in the stopped module*/ 
if (memcmp (Module, 
pgm_dbg_dta->Element [current_view] .ModuleName, 
sizeof (_TE_NAME_T)) != 0) { /* a different module? */ 
for (i=0; i<pgm_dbg_dta->NumberElements; i++) { 
if (memcmp (Module, 
pgm_dbg_dta-—>Element [i] .ModuleName, 


sizeof (_TE_NAME_T)) == 0) { /* found module */ 

current_view = i; /* change current view to module */ 
printf ("Current view changed to %d.\n",current_view) ; 

break; /* exit search loop mf 

} /* module found */ 

} /* loop through views iA 

} /* current view to be changed */ 

/* Get number of statement view for module stopped */ 


for (i=0; i<pgm_dbg_dta->NumberElements; i++) { 
if ((memcmp (Module, 
pgm_dbg_dta->Element [i] .ModuleName, 
sizeof (_TE_NAME T)) == 0) && 
(memcmp ("*STATEMENT", 
pgm_dbg_dta-—>Element [i] .ViewType, 
sizeof (_TE_NAME T)) == 0)) 


stmt_view = i; 
} 
/* Call QteMapViewPosition to map the stopped location (which */ 
/* is in terms of the *STATEMENT view) to the current view of */ 
/* the module *f 


QteMapViewPosition((char *) &Map_Return_Structure, &MapLength, 
épgm_dbg_dta-> Element [stmt_view] .ViewNumber, 
&Statements[0], &Column, 
épgm_dbg_dta-—>Element [current_view] .ViewNumber, 
&errorCode) ; 


/* Tell the user about the program that stopped. nd 
for (i=0;i<4;it+) { /* See why program stopped ay 
if (reason[i] == '1") { 


switch(i) { 
case 0: printf("Unmonitored exception"); 


break; 

case 1: printf ("Breakpoint"); 
break; 

case 2: printf("Step completed") ; 
break; 


case 3: printf("Breakpoint condition error"); 
break; 


} 
} 
printf(" in module %.10s at line %d.\n", 
Module, 
Map_Return_Structure.MapElem[0].LineNumber) ; 


ProcessCommands () ; /* put user into debugger */f 


} 


This function is called when program DEBUG is called as a Program Stop Handler. It is passed the name, library, and type of the 
program stopped, the line number in the statement view where it has stopped, a count of line numbers stopped in, if the system cannot 
determine exactly where the program has stopped (this is the case for optimized code), and an array of character flags indicating why 
the program was stopped. 


The first thing the function does is determine if the current view is set to the module where the program stopped. If not, then it needs 
to be reset to the first view in the module where the program has stopped. 


Next, the statement view ID for the module stopped needs to be determined. This is necessary because the stopped position is given 
in terms of the statement view, and this position needs to be converted to a position in the current view. 


The QteMapViewPosition API maps a position in the statement view to a statement in another view in that module. This allows the 
debugger to determine the source line of the current view where the program has stopped, even though the program is only told the 
line number in the statement view. 


Finally, the character flags are checked to see why the program was stopped. Note that the program can be stopped for more than one 
reason, so every flag is checked, and if it is on, a message for that flag is printed. 


Finally, the ProcessCommands function is called, allowing the user to enter debug commands. 


Other APIs 


This section discusses other APIs not covered in this example debugger. Some or all of these APIs could be used in a real ILE 
source-level debugger. All of them are used in the debugger shipped with OS/400. 


QteRetrieveDebugAttributes 


This API allows a debugger to retrieve information about the debug session. This includes the value of the Update Production Files, 
set on the Start Debug command, as well as an indication of whether the job where the debugger is running is servicing and 
debugging another job. 


QteSetDebugA ttributes 


The only attribute that can be set is the value of the Update Production Files. This can also be accomplished using the Change Debug 
(CHGDBG) CL command. 


QteRemoveDebugView 


Views that are registered can be removed from debug. This is desirable if a program is to be removed from debug so that it can be 
recompiled and added again. It is not necessary to remove views from debug when ending the debug session, as QteEndSourceDebug 
will do this automatically. 


QteRetrieveStoppedPosition 


This indicates if a program is currently stopped and on the stack, and whether this stopped position is anywhere in a given view. This 
is useful whenever a source debugger is about to put up a source screen. If the program is stopped somewhere within the source to be 
displayed, this can be indicated to the user. 


This is necessary because a program can be stopped by other means than the debugger. For example, an ILE program could have put 
up a command entry screen, and the debugger could be displayed from there. In this case, it is nice to indicate to the user that the 
program being debugged is stopped. 


QteAddBreakpoint 


This and the following APIs are not really needed, as their function can be done with the QteSubmitDebugCommand. However, this 
API is much faster, since a debug language command does not need to be parsed and interpreted. In cases where the debugger knows 
the information without needing to specify a debug command to the API, these "shortcut" APIs should be used. 


This API performs the same function as the break n debug language command. 
QteRemoveBreakpoint 

This API performs the same function as the clear n debug language command. 
QteRemoveAllBreakpoints 

This API performs the same function as the clear pgm debug language command. 
QteStep 


This API performs the same function as the step n into and step n over debug language commands. 


Debugger Code--Sample 
Following is the entire program listing for the ILE C program containing the example debugger discussed in the preceding sections. 


[KK RK KK KK KK KKK AA IA AA A A A AA IA IA A A A I A I I / 
[BKK RK KK KKK KK IK A IA A A A AAA AA IAA A A I A I / 


/* a f 
/* FUNCTION: The entire program listing for the program */ 
ee containing the example debugger discussed in the */ 
/* preceding sections. */ 
Ls */ 
/* LANGUAGE: ILE C for OS/400 wee 
is * 
/* APIs USED: QteRetrieveViewText, QteSubmitDebugCommand, */ 
/* QteEndSourceDebug, QteRetrieveModuleViews, */ 
/* QteRegisterDebugView, QteStartSourceDebug, */ 
ps QteMapViewPosition */ 
aa #f 


[KK RK KK KKK KKK KK IA IA IA A A RA IAA IA A I A I A I I He / 
[ORK RK KKK KK KK IK AA A A A A A AA A A A A I A I I He / 


#include <stdio.h> 

#include <string.h> 
#include <stdlib.h> 
#include <qtedbgs.h> 


/* Global variables holding information about a program in debug mode*/ 


static _TE_VEWL0100_T *pgm_dbg_dta = NULL; 
static long current_view = 0; /* current view -— defaults to l1st*/ 
static _TE_OBJLIB_T program_lib; /* name and lib of pgm debugged */ 
/* ReadLine: Reads a line of input and stores it in a string. */ 
void ReadLine(char *Buffer, int length) { 

int: ae /* loop counter %[f 


printf ("Enter a debugger command or ‘'help'.\n"); 


fgets (Buffer, length, stdin) ; /* read line of text xf. 
/* Blank out line from \n to the end of the string. xy: 
for (i=0; i<length; i++) { /* loop, searching for newline */ 
if (Buffer[i] == '\n') { /* if newline character found 
*/ 
break; /* end loop searching for newline*/ 
} 
} 
memset (Bufferti,' ',length-i); /* blank remainder of line * / 


} 


/* PrintText: This function will print the text for the current view */ 
void PrintText (void) { 


long LineLength = 92; 

long NumberOfLines = 0; 
long StartLine=1; 

long bufferLength = 100000; 
long viewID; 


E_TEXT_BUFFER_T *buffer; 
TE_ERROR_CODE_T errorCode = 


{O}; 


length of lines of text 

lines to retrieve - 0 = all 
retrieve from line 1 (first) 
size of retrieved text buffer 
view ID of text to retrieve 
text retrieved by API 
Exceptions will be signaled 


ant lee /* points to start of each line 

int line_number; /* line number counter for loop 

/* Get View ID of current view 

viewID = pgm_dbg_dta->Element [current_view] .ViewNumber; 

buffer = malloc (bufferLength) ; /* malloc space for big text buf 

/* Call Retrieve_View_Text for the current view. 

QteRetrieveViewText ((char *)buffer, &bufferLength, &viewID, 
éStartLine, &NumberOfLines, &LineLength, 


&errorCode) ; 


/* Print out the text 
for (i=0,line_number=1; 


line_number <= buffer->NumLines; 


line_number++,i+=LineLength) 
printf ("%3d) %.70s\n", 
} 


free (buffer); 
} 


/* PrintViews: Prints all the views 
void PrintViews (void) { 
int k; 


/* loop through views printing view#, 


line_number, 


{ 
buffer->Textti); 


/* free memory for buffer 


of the program being debugged. 


module, and view desc. text 


k++) { 


for (k=0; k< pgm_dbg_dta-—>NumberElements; 
printf("Sd) %.10s:%.50s", 
k, 
pgm_dbg_dta->Element [k] .ModuleName, 
pgm_dbg_dta->Element [k] .ViewDescription) ; 
if (current_view == k) 


printf ("<---Current\n"); 
else 
printf ("\n"); 


} 


/* ProcessListCommand: 

void ProcessListCommand(void) { 
char *token; 

strtok (NULL, " 


token = We) se 


if (token==NULL) 

printf(""list' must be followed 

else if (strcmp (token, "views") 
PrintViews (); 

else if (strcmp (token, "text") 
PrintText (); 

else 
printf(""list' 


must be followed 
} 


/* ProcessDbgCommand: 


/* 


== 0) 


/* indicate if view is current 


Process list command to list views or text 


af. 
sh 
ays 


*/ 
we 


* 


oA 


xf 


ef: 


ey 


a 


/* pointer to next token of input*/ 


/* get next token in input buffer*/ 


/* list not followed by anything 
by 'views' or 'text'.\n"); 
)/* iff list views 


/* if list text 


/* list <something-else> 
by 'views' or 'text'.\n"); 


This function will process commands sent to 
the QteSubmitDebugCommand API. 


int ProcessDbgCommand(char InputBuffer[80]) { 


ef 
oF 
ed 
ee 


re 


} 


_TE_ERROR_CODE_T errorCode = {64}; /* fill in bytes provided 
char OutputBuffer[4096]; 

struct _TE_RESULT_BUFFER_T *Results; 

long InputBufferLength = 80; 

long OutputBufferLength = sizeof (OutputBuffer) ; 

long view_ID; 

_TE_COMPILER_ID_T *CompilerID; 

int i; 

int return_value = 0; 


view_ID = pgm_dbg_dta->Element [current_view] .ViewNumber; 
CompilerID = &pgm_dbg_dta-—>Element [current_view] .CompilerID; 


as 


/* Give command to QteSubmitDebugCommand */ 
QteSubmitDebugCommand(OutputBuffer, &OutputBufferLength, 
éview_ID, InputBuffer, &InputBufferLength, 
*CompilerID, &errorCode) ; 
if (errorCode.BytesAvailable != 0) { 
printf("Error = %.7s\n",errorCode.ExceptionID) ; 
return return_value; 
} 
/* Process results from QteSubmitDebugCommand */ 
Results = (_TE_RESULT_BUFFER_T *) OutputBuffer; 
/* Loop through Results array ¥/ 
for (i=0; i<Results->Header.EntryCount; itt) { 
switch (Results-—>Data[i].ResultKind) 
{ 
case _TE_kStepR 
printf ("Step set\n"); 
return_value=1; /* indicate step is to be done mf. 
break; 
case _TE_kBreakR : 
printf ("Breakpoint set"); 
break; 
case _TE_kBreakPositionR 
printf(" at line %d\n", 
Results->Data[i].V.BreakPosition.Line) ; 
break; 
case _TE_kExpressionTextR 
printf ("%Ss" 
((char *)Results) + Results-—>Data[i].V. 
ExpressionText.oExpressionText) ; 
break; 
case _TE_kExpressionValueR 
printf(" = %s\n", 
((char *)Results) + Results-—>Data[i].V. 
ExpressionValue.oExpressionValue) ; 
break; 
case _TE_kQualifyR 
printf ("Qual set\n"); 
break; 
case _TE_kClearBreakpointR 
printf ("Breakpoint cleared\n"); 
break; 
case _TE_kClearPgmR 
printf ("All breakpoints cleared\n"); 
break; 
default: /* ignore all other record types */ 
break; 
} /* switch * 
} /* loop through results array */ 


return return_value; 


/* ProcessCommands: Read input from user and process commands. ay 
void ProcessCommands (void) { 

char InputBuffer[80]; 

char *token; 


int i; 
int step=0; /* do an exit for step when 1 eY 
if (pgm_dbg_dta == NULL) { /* if no debug data bad 
printf ("Debug session has ended.\n"); 
exit (0); /* end the debugger */ 
} 
while(!step) { /* read until step or quit cmd * 
ReadLine (InputBuffer, sizeof (InputBuffer) ); 
token = strtok(InputBuffer," "); 
if (token==NULL) continue; /* ignore blank lines ays 
else if (stremp(token,"quit") == 0) /* the quit command? es 
return; /* exit debugger */ 
else if (stremp(token,"list") == 0) /* the list command? * 
ProcessListCommand() ; /* process command */ 
else if (strcemp(token,"switch") == 0) { /* switch command? */ 
token = strtok(NULL," "); /* get view number token */ 
if (token == NULL) 
printf ("'switch' must be followed by a view number.\n"); 
else 
current_view = atoi(token) ; /* switch current view */ 
} 
else if (strcemp(token,"help") == 0) { 
printf("The following are the allowed debugger commands:\n"); 
printf(" list views - lists all views in the program\n"); 
printf(" list text - lists the text of the current view\n"); 
printf(" switch n - changes current view to view n\n"); 
printf(" help - displays this help text\n"); 
printf(" quit - ends the debug session\n"); 
printf ("Other commands are interpreted by the debug support.\n"); 
} 
else { /* pass command to API * / 
/* Undo modifications that strtok did wf 
InputBuffer[strlen(InputBuffer)] = ' '; 


step = ProcessDbgCommand(InputBuffer) ; 
} 


} 


/* TearDownDebugger: End the debugger. * / 
void TearDownDebugger(void) { 
_TE_ERROR_CODE_T errorCode = {8}; /* errors will be ignored */ 
/* Call EndSourceDebug to get out of ILE debug mode ey 


QteEndSourceDebug (&errorCode) ; 


exit (0); /* destroy activation group ef 


} 


/* AddProgram: Add a program to debug mode. */ 
void AddProgram(void) { 


_TE_ERROR_CODE_T errorCode = {0}; /* Signal exceptions on error */ 
_TE_NAME _ Library; /* Lib returned */ 
_TE_TIMESTAMP_T TimeStamp; /* TimeStamp returned wf 
int viewIndex; 

long int iViewID; 

long int iViewLines; 

long rtvModViewDataLength = 8; /* size of receiver buffer */ 


char tempBuffer[8]; /* Temp storage */ 


int i, tempModuleCount; 


/* Call QteRetrieveModuleViews to determine the number of bytes Bf 
/* the receiver variable needs to be to hold all of the views for */ 
/* the program. */ 
pgm_dbg_dta = (_TE_VEWLO100_T *)tempBuffer; 
QteRetrieveModuleViews((char *)pgm_dbg_dta, &rtvModViewDataLength, 
"VEWLO100", &program_lib, 
"*PGM ") "*ALL ", Library, 
&errorCode) ; 
/* Get a buffer large enough to hold all view information * / 
rtvModViewDataLength = pgm_dbg_dta->BytesAvailable; 
pgm_dbg_dta = (_TE_VEWL0100_T *)malloc(rtvModViewDataLength) ; 
/* Call QteRetrieveModuleViews again, passing a big enough buffer. */ 
QteRetrieveModuleViews((char *)pgm_dbg_dta, &rtvModViewDataLength, 
"VEWLO100", &program_lib, 
"*PGM ") "*ALL ", Library, 
&errorCode) ; 
/* If number of elements is zero, program is not debuggable. e/ 
if (pgm_dbg_dta->NumberElements == 0) { 
printf("Program %.10s in Library %.10s cannot be debugged.", 
program_lib.obj, program_lib.1lib); 
TearDownDebugger () ; 
} 
/* Put the library returned by Retrieve Module Views in PgmLib bai f 
memcpy (program_lib.lib, Library, sizeof (_TE_NAME_T)); 
/* Register all views in the program */ 
for (i=0; i < pgm_dbg_dta->NumberElements; itt) { 
QteRegisterDebugView(&iViewID, &iViewLines, Library, TimeStamp, 
éprogram_lib, "*PGM ae 
pgm_dbg_dta-—>Element [i] .ModuleName, 
épgm_dbg_dta-—>Element [i] .ViewNumber, 
&errorCode) ; 
/* overwrite unneeded ViewNumber with obtained view id *Y 
pgm_dbg_dta->Element [i].ViewNumber = iViewID; 
} 
} 
/* Typedef for program list passed to this program at STRDBG time bans 
typedef struct { 
_TE_OBJLIB_T PgmLib; /* Name and Library of program *f 
_TE_NAME_T PgmType; /* program type, *PGM or *SRVPGM */ 
} PgmList_t; 
/* StartUpDebugger: Initialize the debugger. */ 
void StartUpDebugger (PgmList_t ProgramList[], 
int ProgramListCount) { 
_TE_ERROR_CODE_T errorCode = {0}; /* exceptions are generated */ 
_TE_OBJLIB_T StopHandler = {"DEBUG % MAL TBE Wee 
Int. +} 
if (ProgramListCount!=1) { /* is only 1 pgm passed on STRDBG*/ 
printf ("Exactly ONE program must be specified on STRDBG.\n"); 
TearDownDebugger () ; /* end debugger */ 
} 
/* Copy program name to global variables */ 
memcpy (&program_lib, &ProgramList-—>PgmLib, 20); 
/* Call StartSourceDebug: giving the name and library of the */ 


/* stop handler. This will start ILE debug mode 
QteStartSourceDebug(&StopHandler, &errorCode) ; 


AddProgram() ; /* add program to debug 
} 


/* HandleSession: This function is called to handle the session 
/* events STRDBG, DSPMODSRC and ENDDBG. 
void HandleSession(char reason[10], 

PgmList_t ProgramList[], 

int ProgramListCount) { 


if (memcmp (reason, "*START ",10) == 0) /* reason is *START 
StartUpDebugger (ProgramList, ProgramListCount) ; 

else if ( memcmp (reason, "*STOP ",10) == 0) /* reason is *STOP 
TearDownDebugger () ; 

else if ( memcmp(reason,"*DISPLAY ",10) == 0) /* reason *DISPLAY 


ProcessCommands () ; 


} 


/* HandleStop: This function is called to handle stop events like 
/* breakpoint, step, unmonitored exception, etc. 
void HandleStop(_TE_OBJLIB_T *ProgramLib, 

_TE_NAME_T ProgramType, 

_TE_NAME_T Module, 

char reason[10], 

long Statements[], 

int StatementsCount, 

char *message) { 


int i; 

_TE_MAPP0100_T Map_Return_Structure; 

long Column = 1; 

long MapLength = sizeof (Map_Return_Structure) ; 
_TE_ERROR_CODE_T errorCode = {64}; 

long stmt_view; 


/* Tf£ current view is for a different module than the one that is 


ef 


ef: 
ae 
xf 


xf 
oe 


xf 


/* stopped, change current view to first view in the stopped module*/ 


if (memcmp (Module, 
pgm_dbg_dta->Element [current_view] .ModuleName, 


sizeof (_TE_NAME_T)) != 0) { /* a different module? */ 
for (i=0; i<pgm_dbg_dta->NumberElements; i++) { 
if (memcmp (Module, 
pgm_dbg_dta-—>Element [i] .ModuleName, 
sizeof (_TE_NAME_T)) == 0) { /* found module of 
current_view = i; /* change current view to module */ 
printf ("Current view changed to %d.\n",current_view) ; 
break; /* exit search loop */ 
} /* module found */ 
} /* loop through views xy, 
} /* current view to be changed */ 
/* Get number of statement view for module stopped */ 
for (i=0; i<pgm_dbg_dta->NumberElements; i++) { 
if ((memcmp (Module, 
pgm_dbg_dta->Element [i] .ModuleName, 
sizeof (_TE_NAME T)) == 0) && 
(memcmp ("*STATEMENT", 
pgm_dbg_dta-—>Element [i] .ViewType, 
sizeof (_TE_NAME T)) == 0)) 
stmt_view = i; 
} 
/* Call QteMapViewPosition to map the stopped location (which */ 
/* is in terms of the *STATEMENT view) to the current view of */ 


/* the module 


bad 


QteMapViewPosition((char *) &Map_Return_Structure, &MapLength, 
épgm_dbg_dta-> Element [stmt_view] .ViewNumber, 
&Statements[0], &Column, 
épgm_dbg_dta-—>Element [current_view] .ViewNumber, 
&errorCode) ; 


/* Tell the user about the program that stopped. Ba 
for (i=0;i<4;it+) { /* See why program stopped */ 
if (reason[i] == '1") { 


switch(i) { 

case 0: printf("Unmonitored exception"); 
break; 

case 1: printf ("Breakpoint"); 
break; 

case 2: printf("Step completed") ; 
break; 

case 3: printf("Breakpoint condition error"); 
break; 


} 
} 
printf(" in module %.10s at line %d.\n", 
Module, 
Map_Return_Structure.MapElem[0].LineNumber) ; 


ProcessCommands () ; /* put user into debugger */ 
} 
/* main: Entry point for the debugger (session or stop handler) */ 
main (int argc, char *argv[]) { 

if (argc == 4) /* called as source debug program*/ 


HandleSession(argv[1], (PgmList_t *)argv[2], *(int 
*yargv[3]); 
else if (argc == 8) /* called as program stop handler */ 
HandleStop((_TE_OBJLIB_T *)argv[1], argv[2], 
argv[3], argv[4], 
(long *)argv[5], *(int *)argv[6l, 
argv[7]); 
} 


Using the Spawn Process and Wait for Child Process APIs 


The following two examples illustrate programs that use a parent/child relationship. 


See the QlgSpawn--Spawn Process (using NLS-enabled path name) API for an example of supplying parameters in any CCSID. 


Parent Program 


This program acts as a parent to a child program (see Child Program). 


This program demonstrates the use of the spawn() function and the wait() and waitpid() functions in a parent/child relationship. The 
use of file descriptors, the creation of a new process group, arguments passed from parent to child, and environment variables are 
demonstrated. The parent program uses spawn() in three different ways. 


Use the Create C Module (CRTCMOD) and the Create Program (CRTPGM) commands to create this program (see Creating the 
Parent and Child Program). 


Call this program with no parameters (see Calling the Parent Program). 


[ORK RK KK KK KK KIA IA A A A A A AA IA I IA A A A I 
[BKK RK KKK KK KKK KK IA AA IA A A A AAA IA IA A A I A I / 
/* */ 
/* FUNCTION: This program acts as a parent to a child program. ai 


/* LANGUAGE: ILE C for OS/400 Hf 
/* */ 
/* APIs USED: putenv(), spawn(), wait(), waitpid() * / 
ie */ 


[KK RK KKK KK KKK IK A IA A A A A AIA IA AA A I A A I I / 
[KK RK KK KK KK RIK A IA A A RR AA IA IAA A A I A I I / 


#include <errno.h> 
#include <fcntl.h> 
#include <spawn.h> 
#include <stdio.h> 
#include <string.h> 
#include <stdlib.h> 
#include <sys/stat.h> 
#include <sys/types.h> 
#include <sys/wait.h> 
#include <unistd.h> 


#define MAP_NUM 5 
#define ARGV_NUM 6 
#define ENVP_NUM 2 
#define CHILD_PGM "QGPL/CHILD" 


extern char **environ; 


/* This is a parent program that will use spawn() in 3 different *fe 
/* ways for 3 different children. A file is created that is Lag 
/* written to, both by the parent and the 3 children. The end result*/ 
/* of the file will look something like the following: */ 
/* Parent writes Child writes x, 
i */ 
i uf argv[0] getppid() getpgrp() getpid() */ 
ae 2 argv[0] getppid() getpgrp() getpid() */ 
ee 3 argv[0] getppid() getpgrp() getpid() */ 
/* The parent uses wait() or waitpid() to wait for a given child to */ 
/* return and to retrieve the resulting status of the child when it */ 
/* does return. eof 


int main(int argc, char *argv[]) 


{ 


int re; /* BPI return code */ 
int fd, fd_read; /* parent file descriptors * 
char fd_str[4]; /* file descriptor string * / 
char f_path_name[] = "A_File"; /* file pathname * / 
int buf_int; /* write(), read() buffer */ 
char buf_pgm_name [22]; /* read() program name buffer */ 
char spw_path[] = "/QSYS.LIB/QGPL.LIB/CHILD.PGM"; 

/* spawn() *path */ 
int spw_fd_count; /* spawn() fd_count */ 
int spw_fd_map [MAP_NUM]; 

/* spawn() fd_map[] * / 
struct inheritance spw_inherit; /* spawn() *inherit */ 
char *spw_argv[ARGV_NUM]; 

/* spawn() *argv[] */ 
char *spw_envp[ENVP_NUM]; 

/* spawn() *envp[] */ 
int seq_num; /* sequence number */ 
char seq_num_str[4]; /* sequence number string */ 
pid_t pid; /* parent pid */ 
char pid_str[11]; /* parent pid string *«/ 
pid_t pgrp; /* parent process group Pol 
char pgrp_str[11]; /* parent process group string */ 
pid_t spw_child_pid[3]; /* 3 spawn() child pid * / 
pid_t wt_child_pid[3]; /* 3 wait()/waitpid() child pid */ 


int wt_stat_loc[3]; 
/* 3 wait()/waitpid() *stat_loc*/ 
int wt_pid_opt = 0; /* waitpid() option * / 


char env_return_val [16]; 
/* environ var "return_val=" */ 


memset (&spw_inherit, 0x00, sizeof (spw_inherit) ); 


/* Get the pid and pgrp for the parent. */ 
pid = getpid(); 
pgrp = getpgrp(); 


/* Format the pid and pgrp value into null-terminated strings. */ 
sprintf (pid_str, "%Sd", pid); 
sprintf (pgrp_str, "%Sd", pgrp); 


/* Create a file and maintain the file descriptor. */ 
fd = creat (f_path_name, S_IRWXU); 
if (fd == -1) 


{ 
printf ("FAILURE: creat() with errno = %$d\n",errno) ; 
return -1; 


} 


/* Format the file descriptor into null-terminated string. */ 
sprintf(fd_str, "Sd", fd); 


/* Set the spawn() child arguments that are common for each ay: 
/* child. bay 
/* NOTE: The child will always get argv[0] in the *f 
/* LIBRARY/PROGRAM notation, but the * 
/* spawn() argv[0] (spw_argv[0] */ 
/* in this case) must be non-NULL in order to allow additional */ 
/* arguments. For this example, the character pointer spw_path */ 
/* was chosen. */ 
/* NOTE: The parent pid and the parent process group are passed */ 
/* to the child for demonstration purposes only. a 
spw_argv[0] = spw_path; 

spw_argv[1] = pid_str; 

spw_argv[2] = pgrp_str; 

spw_argv[4] = fd_str; 

spw_argv[5] = NULL; 

/* Write a '1' out to the file. */ 
buf_int = 1 


, 
write(fd, &buf_int, sizeof(int)); 


/* The 1st spawn() will use simple inheritance for file ef 
/* descriptors (fd_map[] value is NULL). */ 
spw_fd_count = 0; 

spw_inherit.pgroup = 0; 


seq _num = 1; 
sprintf(seq_num_str, "%d", seq_num) ; 
spw_argv[3] = seq_num_str; 
spw_envp[0] = NULL; 
spw_child_pid[0] = spawn(spw_path, spw_fd_count, NULL, &spw_inherit, 
spw_argv, sSpw_envp) ; 
if (spw_child_pid[0] == -1) 
{ 
printf ("FAILURE: spawn() #1 with errno = %$d\n",errno) ; 
close(fd); 
unlink (f_path_name) ; 
return -1; 


/* NOTE: The parent can continue processing while the child is *f 
/* also processing. In this example, though, the parent will */ 
/* simply /* wait() until the child finishes processing. */ 


/* Issue wait() in order to wait for the child to return. */ 


wt_child_pid[0] = wait (&éwt_stat_loc[0]); 
if (wt_child_pid[0] == -1) 
{ 
printf ("FAILURE: wait() #1 with errno = %d\n",errno); 
close(fd); 
unlink (f_path_name) ; 
return -1; 


/* Check to ensure the child's pid returned from spawn() is the 
/* same as the child's pid returned from wait(), for which 

/* status was returned. 

if ( (spw_child_pid[0] != wt_child_pid[0]) ) 


printf ("FAILURE: spawn() #1 and wait() #1 pid not the same\n" 


/* Check to ensure the child did not encounter an error 
/* condition. 
if (WIFEXITED (wt_stat_loc[0]) ) 
{ 
if (WEXITSTATUS (wt_stat_loc[0]) != 1) 
printf ("FAILURE: wait() exit status = %d\n", 
WEXITSTATUS (wt_stat_loc[0])); 
} 
else 
printf ("FAILURE: unknown child #1 status\n"); 


/* Write a '2' out to the file. 
buf_int = 2; 
write(fd, &buf_int, sizeof(int)); 


/* The 2nd spawn() will use mapping for the file descriptor, 
/* along with the inheritance option to create a new process 
/* group for the child. 

spw_fd_count = 1; 

spw_fd_map[0] = fd; 

spw_inherit.pgroup = SPAWN_NEWPGROUP; 

seq num = 2; 

sprintf (seq_num_str, "%d", seq_num); 


spw_argv[3] = seq_num_str; 

spw_envp[0] = NULL; 

spw_child_pid[1] = spawn(spw_path, spw_fd_count, spw_fd_map, 
&spw_inherit, spw_argv, spw_envp); 

if (spw_child_pid[1] == -1) 


{ 
printf ("FAILURE: spawn() #2 with errno = %$d\n",errno); 
close(fd); 
unlink (f_path_name) ; 
return -1; 


/* NOTE: The parent can continue processing while the child is 
/* also processing. In this example, though, the parent will 
/* simply waitpid() until the child finishes processing. 


/* Issue waitpid() in order to wait for the child to return. 
wt_child_pid[1] = waitpid(spw_child_pid[1], &éwt_stat_loc[1], 
wt_pid_opt); 
if (wt_child_pid[1] == -1) 
{ 

printf ("FAILURE: waitpid() #2 with errno = %d\n",errno); 

close(fd); 

unlink (f_path_name) ; 


return -1; 


} 


/* Check to ensure the child's pid returned from spawn() is the 
/* same as the child's pid returned from waitpid(), for which 


xf 


Sif 


A 
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/* status was returned. 
if ( (spw_child_pid[1] != wt_child_pid[1]) ) 


*f 


printf ("FAILURE: spawn() #2 and waitpid() #2 pid not same\n"); 


/* Check to ensure the child did not encounter an error 
/* condition. 
if (WIFEXITED (wt_stat_loc[1])) 
{ 
if (WEXITSTATUS (wt_stat_loc[1]) != 2) 
printf ("FAILURE: waitpid() exit status = %d\n", 
WEXITSTATUS (wt_stat_loc[1])); 
} 
else 
printf ("FAILURE: unknown child #2 status\n"); 


/* Write a '3' out to the file. 
buf_int = 3; 
write(fd, &buf_int, sizeof(int)); 


/* The 3rd spawn() will use mapping for the file descriptors 
/* with some file descriptors designated as being closed 

/* (SPAWN_FDCLOSED) and the same parent file descriptor mapped 
/* to more than one child file descriptor. In addition, an 

/* environment variable will be set and used by the child. 
spw_fd_count = 5; 


spw_fd_map[0] = SPAWN_FDCLOSED; 
spw_fd_map[1] = SPAWN_FDCLOSED; 
spw_fd_map[2] = fd; 
spw_fd_map[3] = SPAWN_FDCLOSED; 
spw_fd_map[4] = fd; 
spw_inherit.pgroup = 0; 


seq _num = 3; 
sprintf(seq_num_str, "%d", seq_num); 


spw_argv[3] = seq_num_str; 
strcpy (env_return_val, "return_val=3"); 
re = putenv(env_return_val)j; 


if (re < 0) 
{ 
printf ("FAILURE: putenv() with errno = %d\n",errno) ; 
close(fd); 
unlink (f_path_name) ; 
return -1; 


} 


spw_child_pid[2] = spawn(spw_path, spw_fd_count, spw_fd_map, 
éspw_inherit, spw_argv, environ); 
if (spw_child_pid[2] == -1) 


{ 
printf ("FAILURE: spawn() #3 with errno = $d\n",errno) ; 
close(fd); 
unlink (f_path_name) ; 
return -1; 


/* The parent no longer needs to use the file descriptor, so it 
/* can close it, now that it has issued spawn(). 
re = close(fd); 
if (re != 0) 
printf ("FAILURE: close(fd) with errno = %d\n",errno); 


/* NOTE: The parent can continue processing while the child is 
/* also processing. In this example, though, the parent will 
/* simply wait() until the child finishes processing. 


/* Issue wait() in order to wait for the child to return. 
wt_child_pid[2] = wait (&wt_stat_loc[2]); 
if (wt_child_pid[2] == -1) 

{ 


xf 
aA 


if 


Dif 
ad 
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ef 


as 


} 


printf ("FAILURE: wait() #3 with errno = %d\n",errno); 
unlink (f_path_name) ; 
return -1; 


/* Check to ensure the child's pid returned from spawn() is the */ 
/* same as the child's pid returned from wait(), for which */ 
/* status was returned. Lad 
if ( (spw_child_pid[2] != wt_child_pid[2]) ) 
printf ("FAILURE: spawn() #3 and wait() #3 pid not the same\n"); 
/* Check to ensure the child did not encounter an error * / 
/* condition. */ 
if (WIFEXITED (wt_stat_loc[2]) ) 
{ 
if (WEXITSTATUS (wt_stat_loc[2]) != 3) 
printf ("FAILURE: wait() exit status = %d\n", 
WEXITSTATUS (wt_stat_loc[2])); 
} 
else 
printf ("FAILURE: unknown child #3 status\n"); 
/* Open the file for read to verify what the child wrote. ara 
fd_read = open(f_path_name, O_RDONLY); 
if (fd_read == -1) 
{ 
printf ("FAILURE: open() for read with errno = %d\n",errno) ; 
unlink (f_path_name) ; 
return -1; 
} 
/* Verify what child #1 wrote. yA 
re = read(fd_read, &buf_int, sizeof(int)); 
if ( (re != sizeof(int)) || (buf_int != 1) ) 


printf ("FAILURE: read() #1\n"); 


memset (buf_pgm_name, 0x00, sizeof (buf_pgm_name) ) ; 


CC 
if 


te 
if 
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if 
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= read(fd_read, buf_pgm_name, strlen(CHILD_PGM)); 
( (re != strlen (CHILD_PG™M) ) 
(strcmp (buf_pgm_name,CHILD_PGM) != 0) ) 
printf ("FAILURE: read() child #1 argv[0]\n"); 
= read(fd_read, &buf_int, sizeof(int)); 
( (re != sizeof (int) ) (buf_int != pid) ) 
printf ("FAILURE: read() child #1 getppid()\n"); 
= read(fd_read, &buf_int, sizeof(int)); 
( (re != sizeof (int) ) (buf_int != pgrp) ) 
printf ("FAILURE: read() child #1 getpgrp()\n"); 
= read(fd_read, &buf_int, sizeof(int)); 
( (re != sizeof (int) ) (buf_int != spw_child_pid[0]) || 
(buf_int != wt_child_pid[0]) ) 
printf ("FAILURE: read() child #1 getpid()\n"); 


Verify what child #2 wrote. aay f 
= read(fd_read, &buf_int, sizeof(int)); 

( (re != sizeof(int)) || (buf_int != 2) ) 

printf ("FAILURE: read() #2\n"); 


memset (buf_pgm_name, 0x00, sizeof (buf_pgm_name) ) ; 


Ce 
if 


re 


if 


re 
if 


re 


= read(fd_read, buf_pgm_name, strlen(CHILD_PGM)); 

( (re != strlen (CHILD_PG™M) ) 
(strcmp (buf_pgm_name,CHILD_PGM) != 0) ) 

printf ("FAILURE: read() child #2 argv[0]\n"); 

= read(fd_read, &buf_int, sizeof(int)); 

( (re != sizeof(int)) || (buf_int != pid) ) 

printf ("FAILURE: read() child #2 getppid()\n"); 

= read(fd_read, &buf_int, sizeof(int)); 

( (re != sizeof(int)) || (buf_int == pgrp) ) 

printf ("FAILURE: read() child #2 getpgrp()\n"); 

= read(fd_read, &buf_int, sizeof(int)); 


if ( (re != sizeof(int)) || (buf_int != spw_child_pid[1]) || 
(buf_int != wt_child_pid[1]) ) 
printf ("FAILURE: read() child #2 getpid()\n"); 


/* Verify what child #3 wrote. */ 
re = read(fd_read, &buf_int, sizeof(int)); 
if ( (re != sizeof(int)) || (buf_int != 3) ) 
printf ("FAILURE: read() #3\n"); 
memset (buf_pgm_name, 0x00, sizeof (buf_pgm_name) ) ; 
re = read(fd_read, buf_pgm_name, strlen(CHILD_PGM))j; 


if ( (re != strlen(CHILD_PGM) ) 
(strcmp (buf_pgm_name,CHILD_PGM) != 0) ) 
printf ("FAILURE: read() child #3 argv[0]\n"); 
re = read(fd_read, &buf_int, sizeof(int)); 
if ( (re != sizeof (int) ) (buf_int != pid) ) 
printf ("FAILURE: read() child #3 getppid()\n"); 
re = read(fd_read, &buf_int, sizeof(int)); 
if ( (re != sizeof (int) ) (buf_int != pgrp) ) 
printf ("FAILURE: read() child #3 getpgrp()\n"); 
re = read(fd_read, é&buf_int, sizeof(int)); 
if ( (re != sizeof (int) ) (buf_int != spw_child_pid[2]) || 
(buf_int != wt_child_pid[2]) ) 
printf ("FAILURE: read() child #3 getpid()\n"); 
/* Attempt one more read() to ensure there is no more data. *«/ 
re = read(fd_read, &buf_int, sizeof(int)); 
if (re != 0) 


printf ("FAILURE: read() past end of data\n"); 


/* The parent no longer needs to use the read() file descriptor, */ 


/* so it can close it. */ 
re = close (fd_read) ; 
if (re != 0) 


printf ("FAILURE: close(fd_read) with errno = %d\n",errno); 


/* Attempt one more wait() to ensure there are no more children. */ 
wt_child_pid[0] = wait (&éwt_stat_loc[0]); 
if ( (wt_child_pid[0] != -1) || (errno != ECHILD) ) 

printf ("FAILURE: ECHILD wait()\n"); 


/* Clean up by performing unlink(). */ 
re = unlink (f_path_name) ; 
if (re != 0) 


{ 
printf ("FAILURE: unlink() with errno = %$d\n",errno) ; 
return -1; 


} 
printf ("completed successfully\n"); 
return 0; 


Child Program 


This program acts as a child to a parent program (see Parent Program). This program demonstrates how a child program uses 
characteristics expressed through the use of spawn() in the parent program. The use of file descriptors, the creation of a new process 
group, arguments passed from the parent, and environment variables are demonstrated. The child program handles three distinct calls 
through the use of one of its arguments. 


Use the CRTCMOD and CRTPGM commands to create this program (see Creating the Parent and Child Program). 


This program is called by the spawn() function from the parent program. The program name must be CHILD and must be created into 
library QGPL, as indicated by the parent program. This program is not to be called directly. 


[BKK RK KK KKK KK KK IK AA IA A I A A AAA AA IA A A I A I / 
[OK KK KK KKK KKK I IA IA A A A A A AA IA IA AA A A I A I I 


/* FUNCTION: This program acts as a child to a parent program. */ 
‘hag */ 
/* LANGUAGE: ILE C for OS/400 A 
(he * 
/* APIs USED: getenv(), getpid(), getppid(), getpgrp() */ 
fag */ 


[KK RK KK KK KKK IK IA AA A A I A A IA IA AA AA I A I A I I / 
[BKK RK KK KKK KK I A AA A A A A A IA IA A A A I A I I He / 


#include <stdlib.h> 
#include <string.h> 
#include <sys/types.h> 
#include <unistd.h> 


/* This is a child program that gets control from a parent program 


/* that issues spawn(). This particular child program expects the 
/* following 5 arguments (all are null-terminated strings): 

1% argv[0] - child program name 

br argv[1l] - parent pid (for demonstration only) 

x argv[2] - parent process group (for demonstration only) 

/* argv[3] - sequence number 

f argv[4] - parent file descriptor 

/* If the child program encounters an error, it returns with a value 


greater than 50. If the parent uses wait() or waitpid(), this 
return value can be interrogated using the WIFEXITED and 
WEXITSTATUS macros on the resulting wait() or waitpid() 
*stat_loc field. 


int main(int argc, char *argv[]) 


{ 


pid_t p_pid; /* parent pid argv[1] 

pid_t p_pgrp; /* parent process group argv[2] 
int seq_num,; /* parent sequence num argv[3] 
int fd; /* parent file desc argv[4] 

int rc; /* API return code 

pid_t pid; /* getpid() - child pid 
pid_t ppid; /* getppid() - parent pid 
pid_t pgrp; /* getpgrp() - process group 
char *env_return_val; /* environ var for "return_val" 


/* Get the pid, ppid, and pgrp for the child. 
pid = getpid(); 

ppid = getppid(); 

pgrp = getpgrp(); 


/* Verify 5 parameters were passed to the child. 
if (arge != 5) 
return 60; 


/* Since the parameters passed to the child using spawn() are 
/* pointers to strings, convert the parent pid, parent process 
/* group, sequence number, and the file descriptor from strings 
/* to integers. 

p_pid = atoi(argv[1]); 
p_pgrp = atoi(argv[2]) 
seq_num = atoi(argv[3] 
fd = atoi(argv[4]); 


; 


/* Verify the getpid() value of the parent is the same as the 
/* getppid() value of the child. 
if (p_pid != ppid) 

return 61; 


/* If the sequence number is 1, simple inheritance was used in 
/* this case. First, verify the getpgrp() value of the parent 
/* is the same as the getpgrp() value of the child. Next, the 
/* child will use the file descriptor passed in to write the 


* 


rr 
a 


ef 
ys 


/* child's values for argv[0], getppid(), getpgrp(), xf 


/* and getpid(). Finally, the child returns, which will satisfy 
/* the parent's wait() or waitpid(). 
if (seq_num == 1) 
{ 
if (p_pgrp != pgrp) 
return 70; 
re = write(fd, argv[0], strlen(argv[0])); 
if (re != strlen(argv[0])) 


/* 
els 


{ 


/* 


return 71; 
re = write(fd, &ppid, sizeof (pid_t)); 
if (re != sizeof (pid_t) ) 

return 72; 
re = write(fd, &pgrp, sizeof (pid_t)); 
if (re != sizeof (pid_t) ) 

return 73; 
re = write(fd, &pid, sizeof (pid_t)); 
if (re != sizeof (pid_t) ) 

return 74; 
return seq_num; 


If the sequence number is 2, file descriptor mapping was used 
in this case. In addition, an inheritance option was used to 
indicate this child will create a new process group. First, 
verify the getpgrp() value of the parent is different than 
the getpgrp() value of the child. Next, the child will use 

a literal value of '0' as the file descriptor (instead of the 
parent's file descriptor passed in) since a known mapping was 
performed by the parent. This literal is used to write the 


child's values for argv[0], getppid(), getpgrp(), 
and getpid(). Finally, the child returns, which will satisfy 
the parent's wait() or waitpid(). 
e if (seq_num == 2) 

if (p_pgrp == pgrp) 

return 80; 
re = write(0, argv[0], strlen(argv[0])); 
if (re != strlen(argv[0]) ) 


return 81; 
re = write(0, &ppid, sizeof (pid_t)); 
if (re != sizeof (pid_t) ) 

return 82; 
re = write(0, &pgrp, sizeof (pid_t)); 
if (re != sizeof (pid_t) ) 

return 83; 
re = write(0, &pid, sizeof (pid_t)); 
if (re != sizeof (pid_t) ) 

return 84; 
return seq_num; 


If the sequence number is 3, file descriptor mapping was used 
in this case. In addition, an environment variable by the 
name of "return_val" was set with the desired return value. 
First, verify the getpgrp() value of the parent is the same 
as the getpgrp() value of the child. Next, the child will 
use literal values of '2' and '4' as the file descriptor 
(instead of the parent's file descriptor passed in) since a 
known mapping was performed by the parent. These literals 
are used to write the child's values for argv[0], getppid(), 
getpgrp(), and getpid(). Finally, getenv() is performed to 
retrieve the desired value to use on return, which will 
satisfy the parent's wait() or waitpid(). 


else if (seq_num == 3) 


{ 


if (p_pgrp != pgrp) 


af 
a 


return 90; 
re = write(4, argv[0], strlen(argv[0])); 
if (re != strlen(argv[0]) ) 

return 91; 
re = write(2, &ppid, sizeof(pid_t)); 
if (re != sizeof (pid_t) ) 

return 92; 
re = write(4, &pgrp, sizeof (pid_t)); 
if (re != sizeof (pid_t) ) 

return 93; 
re = write(2, &pid, sizeof (pid_t)); 


if (re != sizeof (pid_t) ) 
return 94; 
env_return_val = getenv("return_val"); 


return (atoi(env_return_val))j; 


} 


/* If the sequence number is an unexpected value, return * / 
/* indicating an error. */ 
else 


return 99; 


Creating the Parent and Child Program 


The following examples show how to create the example programs (Parent Program and Child Program). These examples assume 


that the source for the parent program is member PARENT in the file QGPL/QCSRC and the source for the child program is member 
CHILD in the file QGPL/QCSRC. 


Create the parent module: 


CRTCMOD MODULE (QGPL/PARENT) 
SRCFILE (QGPL/QCSRC) 
SRCMBR (PARENT) 
TEXT ('Example Parent') 


Create the child module: 


CRTICMOD MODULE (QGPL/CHILD) 
SRCFILE (QGPL/QCSRC) 
SRCMBR (CHILD) 
TEXT ('Example Child") 


Create the parent program: 


CRTPGM PGM(QGPL/PARENT) 


Create the child program: 


CRTPGM PGM(QGPL/CHILD) 


Calling the Parent Program 
The following example shows how to start the example programs: 


CALL PGM(QGPL/PARENT) 


Working with Stream Files 


The following ILE C program performs the following functions: 


e@ Opens an existing stream file 
@ Creates or replaces a database file 
e Reads from the stream file and writes to the database file until end-of-file 


e Closes both files 


The program uses the following hierarchical file system (HFS) APIs: 
e Create Directory (QHFCRTDR) 


e Open Stream File (QHFOPNSF) 
e Read from Stream File (QHFRDSF) 


e Close Stream File (QHFCLOSF) 


[KK RK KKK KK KK KK IK IA AA A I I AA AAA AA A A a I A / 


/* Program Name: HFSCOPY 


/* Language : ILE C for 0OS/400 

/* Description : This program will do the following: 

Vas) —— Create or replace a stream file 

he —— Create or replace a database file 

/* —— Read from the stream file and write to the 
‘fag database file until EOF 

eg -- Close both files when done 

/* APIs Used : QHFCRTDR, QHFOPNSF, QHFRDSF, QHFCLOSE 


[KKK KK KK KK KKK IA IA AA IA I I A AA AAA IA A A I a I a / 


[KKK KK KK KKK KKK IA AA AA IA I A A AA AA IA A I a / 


/* Include files 


fe 


[ORK RK KK KK KK KK IR IA IA A I A A A AIA IA A a 


#include <stdio.h> 
#include <stdlib.h> 
#include <string.h> 
#include <qhfopnsf.h> 
#include <qhfrdsf.h> 
#include <qhfclosf.h> 
#include <qhfcrtdr.h> 
#include <qusec.h> 


[KK RK KK KK KKK IR IA IA A I I A AAA AA AA A a I I / 


/* Structure and variable definitions 


aes 


[KK RK KK KKK KK KKK IK IA AA IA A AAA AA IA IA A a I A / 


#define ON 1 

#define OFF 0 

typedef struct error_code_struct { 
Qus_EC_t EC; 
char exception_data[256]; 
}error_code_struct; 

error_code_struct error_code; 

char file_handle[16]; 

char path_name[30]; 

char open_info[10]; 

char attrib_info; 

char action; 

char read_buffer[80]; 

int path_length; 


int attrib_length = 0; 
int bytes_to_read; 

int bytes_read = 0; 
int end_file; 

int cmpgood; 

FILE *FP; 


[KK RK KKK KK KK I A A A A A A A IA AA A A A A A I I / 


/*printErrCode: Routine to print the error code structure aah 
[KK RK KK KK KKK IK A A A A A A A IA AA A A A A I I I / 
void printErrCode(error_code_struct *theErrCode) 
{ 

int i; 

char *tempptr = theErrCode->EC.Exception_Id; 

printf ("Bytes Provided -> %d\n",theErrCode->EC.Bytes_Provided) ; 

printf ("Bytes Available -> %$d\n",theErrCode->EC.Bytes_Available) ; 

printf ("Exception ID -> "); 

for (i=0;i<7 ;i++,tempptrt+ ) 

{ 
putchar (*tempptr); 


} 
putchar('\n"'); 


[KKK KK KK KK IK IA IA AA IA I I A AA A A AA A I I I / 


/* Start of code ef 


[ORK RK KK KK KK KK IA IA IA IA I A A AA AAA AA A A a I 


main () 


{ 


error_code.EC.Bytes_Provided = 116; 
[OK KK KK KKK KK KK IA IA IA A I I AAA AAA AA A A a I / 


/* Create the directory af 
[ORK RK KKK KK KK KK IK AA AA A I I A AAA AA AA A A a I A / 
strcpy (path_name, "/QDLS/HFSFLR") ; 
path_length = strlen(path_name) ; 


QHFCRIDR(path_name, path_length, éattrib_info, attrib_length, &error_code) ; 
if ( error_code.EC.Bytes_Available != 0 ) 
{ 
if (!memcmp (error_code.EC.Exception_Id,"CPF1F04",7) ) 
printf ("Directory HFSFLR already created.\n"); 
else 
{ 
printErrCode (&error_code) ; 
exit (1); 
} 
} 


[KKK KK KKK KK KKK IR AA IA IA I I I I A A AAA AAA A A I I / 


/* Open the stream file aA 
[OK KK KKK KKK KK KK IK IA IA IA I I I A AA AA AA A A I He A / 
strcpy (open_info,"210 120 M3 /* Create or replace the file * / 


strcpy (path_name, "/QDLS/HFSFLR/SAMPLE.HFS") ; 
path_length = strlen(path_name) ; 
printf("OPEN STREAM FILE:\n "); 
QHFOPNSF (&file_handle, 

path_name, 

path_length, 

open_info, 

éattrib_info, 

attrib_length, 

éaction, 

&error_code) ; 
if (error_code.EC.Bytes_Available != 0) 

{ 


printErrCode(&error_code) ; 
exit (1); 
} 


[ORK RK KKK KK KK KK IK IA IA A I AA AA AAA AA A A I I A / 


/* Open a database file mp 
[ORK RK KKK KK KK KR IA IA IA A I A AA AA A A I a / 
system("CRTLIB LIB(HFSLIB)"); 
if (( FP = fopen("HFSLIB/HFSFILE (SAMPLE)","wb")) == NULL) 

{ 

printf("Cannot open HFSLIB/HFSFILE (SAMPLE) \n") ; 

exit (1); 

} 


[ORK RK KK KK KK KK IA AA IA A I I A A AA AA AA A A a I 


/* Loop through reading from the stream file and writing to the */ 
/* database file. */: 


[OK KK KKK KK KK KKK IK AA AA A I I A AA AAA AA A A I I I a / 


end_file = OFF; 
while (end_file == OFF) 
{ 


[ROKK RK KK KK KK KK IA A A A A I A A A A A OA He / 


/* Read 80 bytes from the stream file awe 
[ORK RK KK KK KK KK A A A A I I A A A A OA A A I / 
bytes_to_read = 80; 
printf ("READ STREAM FILE:\n "); 
QHFRDSF (&file_handle, 
read_buffer, 
bytes_to_read, 
&bytes_read, 
&error_code) ; 
if (error_code.EC.Bytes_Available != 0) 
{ 


cmpgood = strnemp ("CPF1F33",error_code.EC.Exception_Id,7)j; 
if (cmpgood != 0) 

printErrCode (&error_code) ; 
end_file = ON; 


else 
{ 
printf ("BYTES READ: %d\n ",bytes_read); 
printf ("READ BUFFER: %s\n",read_buffer) ; 
if (bytes_read < bytes_to_read) 
{ 
end_file = ON; 


[BORK KK KK KK I A AA I I A A I / 


/* Write remaining bytes to the database file WA 
[ORK KK RK KK KK A I I A I A  / 


if (bytes_read > 0) 
fwrite(read_buffer,1,bytes_read, FP) ; 


} 


[ORK RK KK KKK KK KK IK AA IA A I A AAA AA A A a I a / 


/* Close the stream file */ 
[KK RK KK KKK KK KK IK IA IA A I A AA AA AA A A I He a / 
printf("CLOSE STREAM FILE:\n "); 


QHFCLOSF (&file_handle, 
&error_code) ; 
if (error_code.EC.Bytes_Available != 0) 
printErrCode (&error_code) ; 


[BOK KK KK KK KK KKK IR IA IA IA I I A A A AA AA A A a 


/* Close the database file ay 


[KKK KK KK KK KK KR IA IA IA I I I A AA AAA A A I a I / 


fclose(FP); 
} 


To create the program using ILE C, specify the following: 


CRTBNDC PGM(QGPL/HFSCOPY) SRCFILE (QGPL/QCSRC) 


Using the Operational Assistant Exit Program for 
Operational Assistant Backup 


The following contains a CL example of a user-written exit program for doing Operational Assistant backup. 


[BOR KR KKK KKK KK KKK IA IA IA I I I I A A A A A A I I He / 
[KKK KKK KK KK KKK IR IA IA A I I I A A A A A A I / 


f% id 
/* FUNCTION: User-written exit program for doing Operational */ 
/* Assistant backup. a), 
/* */ 
/* LANGUAGE: CL */ 
(os tif 
/* APIs USED: None */ 
[* */ 


[OK KR KKK KK KK KKK KR IA IA A I I I A A A A A A A a I He / 
[OK KKK KKK KK KK KR IR IA AA I I I A A A A A 


PGM PARM(&PRODID &FLAG &OPTIONS &DEVS &TAPSET &RETCODE) 
DCL VAR(&PRODID) TYPE (*CHAR) EN (10) /* Calling product. + 

Will be 'QEZBACKUP' when called from + 

Operational Assistant. mo: 
DCL VAR(&FLAG) TYPE(*CHAR) LEN(10) /* Indicates whether + 

before or after backup. #y 

DCL VAR(&DEVS) TYPE(*CHAR) LEN(40) /* Devices used. */ 
DCL VAR(&TAPSET) TYPE(*CHAR) LEN (4) /* Tape set name */ 
DCL VAR(&RETCODE) TYPE(*CHAR) LEN(7) /* Return code ay 
DCL VAR(&OPTIONS) TYPE(*CHAR) LEN(10) /* Options used */ 
DCL VAR(&MSG) TYPE(*CHAR) LEN (512) /* Message text ey 
IF COND (&FLAG *EQ '*BEFORE ') THEN (DO) 
(as Ky 
/* Insert commands to be run before the backup here. a1 
[* ia A 
ENDDO 
IF COND (&FLAG *EQ '*AFTER ') THEN (DO) 
/* *] 
/* Insert commands to be run after the backup here. */ 
is KY, 
ENDDO 
ENDPGM 


Creating a Program Temporary Fix Exit Program 


This example exit program written in CL, covers the following possible changes in the logical state of the PTF: 
Loaded to temporarily applied 


Temporarily applied to temporarily removed 


The example program shows where you can add your code. You can write a PTF exit program in any programming language. 


Note: This example does not show the apply-temporary to apply-permanent or the not-applied to remove-permanent cases. It is 
assumed that all action was taken on the moves from loaded to apply-temporary and from apply-temporary to not-applied. If 
additional actions are necessary, code could be added to handle those transitions as well. 


Do not assume the default values for parameters on CL commands or for library lists. Users can change these values. Library lists can 
vary from one system to another. 


[KKK START OF SPECIFICATIONS Fe KK KK A A I  / 


/* #, 
/* LANGUAGE: CL */ 
/* Ay 
/* APIs USED: None A 
/* * / 
/* FUNCTION: ay A 
lag THIS EXIT PROGRAM IS CALLED DURING ANY an 
ye OF THE FOLLOWING CASES. mf 
/* %/ 
/* APPLY TEMPORARILY - (user defined) */ 
/* * / 
/* APPLY PERMANENTLY —- (user defined) *f 
/* * / 
/* REMOVE TEMPORARILY - (user defined) *y: 
f* */ 
/* REMOVE PERMANENTLY - (user defined) */ 
ee * / 
/* Input: PARM1 - CHAR(7) —- Product ID */ 
/* PARM2 CHAR(7) —- PTF ID */ 
/* PARM3 - CHAR(6) - Product release # 
/* PARM4 CHAR(4)  —- Product option ID */ 
/* PARM5 CHAR(4) —- Product load ID */ 
/* PARM6 CHAR(10) - PTF library */ 
/* PARM7 CHAR(50) - User data iA 
/* PARM8 - CHAR(1) - Current PTF Status ia A 
/* 0 - LOADED BUT NOT APPLIED */ 
®t 1 - APPLIED TEMPORARILY mf 
/* PARM9 CHAR(1) —- PTF Operation EA 
[* 0 - REMOVE TEMPORARILY */ 
/* 1 - APPLY TEMPORARILY */ 
Px 2 - APPLY PERMANENTLY xf 
/* 3 —- REMOVE PERMANENTLY */ 
[% 4 -— PRE-REMOVE TEMPORARILY xy: 
/* 5 - PRE-APPLY TEMPORARILY ae 
Ex 6 - PRE-APPLY PERMANENTLY *ef 
/* 7 - PRE-REMOVE PERMANENTLY */ 
Is * / 
/* bad 


[RKRKK KKK END OF SPECIFICATIONS FER KK KK A A AA I  / 


PGM PARM(&PARM1 &PARM2 &PARM3 &PARM4 &PARM5 &PARM6 &PARM7 &PARM8 &PARMQ) 


fe */ 
/* Ay 
/* DECLARE INPUT PARAMETERS mf 
/* */ 
es * / 
DCL &PARM1 TYPE (*CHAR) LEN(7) /* Product ID */ 
DCL &PARM2 TYPE (*CHAR) LEN(7) /* PTF ID * / 
DCL &PARM3 TYPE (*CHAR) LEN (6) /* Product release * / 
DCL &PARM4 TYPE (*CHAR) LEN (4) /* Product option ID */ 
DCL &PARM5 TYPE(*CHAR) LEN (4) /* Product load ID */ 
DCL &PARM6 TYPE(*CHAR) LEN(10) /* PTF library */ 
DCL &PARM7 TYPE (*CHAR) LEN(50) /* User data * / 
DCL &PARM8 TYPE (*CHAR) LEN(1) /* Current PTF status x 
DCL &PARM9 TYPE (*CHAR) LEN(1) /* PTF operation */ 


/* 

/* 

/* DECLARE VARIABLES 

/* 

/* 

DCL &ACTION TYPE (*CHAR) LEN(1) /* PTF action to occur 

DCL &STATUS TYPE (*CHAR) LEN (1) /* PTF current status 
/* Handle exceptions 

MONMSG MSGID(CPFO000) EXEC (GOTO CMDLBL(HDLERR) ) 


CHGVAR VAR(&ACTION) VALUE(&PARM9) /* Gets action being performed 
CHGVAR VAR(&STATUS) VALUE(&PARM8) /* Gets current PTF status 
/* 
/* THE CURRENT STATUS OF THE PTF IS "LOADED (NOT APPLIED)" 
/* 
IF (&STATUS = '0') THEN(DO) /* If PTF is loaded but not applied 
IF (&ACTION = '1') THEN(DO) /* If action is temporarily 
/* applied then 
/*?---- TEMP APPLY - ADD YOUR STATEMENTS HERE ----- 
ENDDO 
IF (&ACTION = '5') THEN (DO) /* Tf action will be temporarily 
/* apply then 
/*?---- PRE-TEMP APPLY - ADD YOUR STATEMENTS HERE ----- 
ENDDO 
ENDDO /* End of loading the PTF 
/* 
/* THE CURRENT STATUS OF THE PTF IS "APPLIED TEMPORARILY" 
/* 
IF (&STATUS = '1') THEN (DO) /* If PTF is temporarily 
/* applied then 
IF (&ACTION = '0') THEN (DO) /* If action is temporarily 
/* removed then 
/*?---- TEMPORARILY REMOVE - ADD YOUR STATEMENTS HERE --- 
ENDDO 
IF (&ACTION = '4') THEN (DO) /* Tf action will be temporarily 
/* remove then 
/*?---- PRE-TEMP REMOVE - ADD YOUR STATEMENTS HERE ----- 
ENDDO 
ENDDO /* End of remove the PTF 
/* 
/* PTF HAS BEEN SUCCESSFULLY PROCESSED 
/* 
QSYS/SNDPGMMSG MSGID(CPC1214) MSGF(*LIBL/QCPFMSG) + 
MSGDTA(*NONE) TOPGMQ(*PRV (* *NONE + 
*NONE) ) TOMSGQ(*TOPGMQ) MSGTYPE (*COMP) 
RETURN 
/* 
/* HANDLE ALL ERROR CONDITIONS 
/* 
HDLERR: 


/* Try to back out any changes already made */ 


/* If nothing to back out or back-out operation was successful 


QSYS/SNDPGMMSG MSGID(CPF3638) 


MSGF (*LIBL/QCPFMSG) + 


MSGDTA (*NONE) TOPGMQ(*PRV (* *NONE + 

*NONE) ) TOMSGQ(*TOPGMQ) MSGTYPE (*ESCAPE) 
/* Else the permanent changes not backed out */ 
QSYS/SNDPGMMSG MSGID(CPF3639) MSGF(*LIBL/QCPFMSG) + 

MSGDTA (*NONE) TOPGMQ(*PRV (* *NONE + 


*NONE) ) TOMSGQ (*TOPGMQ) 


ENDPGM 


Top | APIs by category 


MSGTYPE (*ESCAPE) 


/* Return to external caller 


*/ 


